<HTML>
<HEAD>
<TITLE> C-Kernel Required Reading </TITLE>
</HEAD>

<BODY style="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);">

<A NAME="top"></A>

<TABLE STYLE="text-align: left; margin-left: auto; margin-right: auto; width: 800px;" BORDER="0" CELLPADDING="5" CELLSPACING="2">
<TBODY>
<TR>
  <TD STYLE="background-color: rgb(153, 153, 153); vertical-align: middle; text-align: center;">
  <DIV ALIGN="right">
    <SMALL><SMALL><A HREF="index.html">Index Page</A></SMALL></SMALL>
  </DIV>
  <B>C-Kernel Required Reading</B> </TD>
</TR>
<TR>
  <TD STYLE="vertical-align: top;">

<H2> Table of Contents
</H2>

<PRE>
   <A HREF="#C-Kernel Required Reading">C-Kernel Required Reading</A>
      <A HREF="#Abstract">Abstract</A>
   <A HREF="#References">References</A>
   <A HREF="#DAF Run-Time Binary File Format Translation">DAF Run-Time Binary File Format Translation</A>
   <A HREF="#Detection of Non-native Text Files">Detection of Non-native Text Files</A>
   <A HREF="#Introduction">Introduction</A>
   <A HREF="#Preliminaries">Preliminaries</A>
      <A HREF="#Specifying Spacecraft and Instruments">Specifying Spacecraft and Instruments</A>
      <A HREF="#C-Matrices">C-Matrices</A>
      <A HREF="#Angular Velocity Vectors">Angular Velocity Vectors</A>
      <A HREF="#Spacecraft Clock Time">Spacecraft Clock Time</A>
         <A HREF="#Encoded SCLK">Encoded SCLK</A>
         <A HREF="#Ticks and Partitions">Ticks and Partitions</A>
         <A HREF="#SCLK and other time systems">SCLK and other time systems</A>
         <A HREF="#The SCLK kernel file">The SCLK kernel file</A>
   <A HREF="#Basics">Basics</A>
      <A HREF="#The CK File Reader ckgp_c">The CK File Reader ckgp_c</A>
         <A HREF="#furnsh_c">furnsh_c</A>
         <A HREF="#scencd_c and sce2c_c">scencd_c and sce2c_c</A>
         <A HREF="#sctiks_c">sctiks_c</A>
         <A HREF="#ckgp_c">ckgp_c</A>
      <A HREF="#The CK File Reader ckgpav_c">The CK File Reader ckgpav_c</A>
      <A HREF="#Multiple Files and the C-kernel">Multiple Files and the C-kernel</A>
      <A HREF="#CK Coverage Summary Routines">CK Coverage Summary Routines</A>
   <A HREF="#Details">Details</A>
      <A HREF="#File Structure and Implementation">File Structure and Implementation</A>
         <A HREF="#Segment Descriptors">Segment Descriptors</A>
         <A HREF="#Segment Identifiers">Segment Identifiers</A>
         <A HREF="#Comment Area">Comment Area</A>
         <A HREF="#A CK file is a DAF">A CK file is a DAF</A>
         <A HREF="#SPICE File Identification Word in CK Files">SPICE File Identification Word in CK Files</A>
      <A HREF="#How the CK Readers Work">How the CK Readers Work</A>
         <A HREF="#The General Search Algorithm">The General Search Algorithm</A>
         <A HREF="#The Difference Between ckgp_c and ckgpav_c">The Difference Between ckgp_c and ckgpav_c</A>
         <A HREF="#Locating the Applicable Segment">Locating the Applicable Segment</A>
         <A HREF="#Looking at Descriptors">Looking at Descriptors</A>
         <A HREF="#Evaluating the Records --- the Reader ckpfs_">Evaluating the Records --- the Reader ckpfs_</A>
         <A HREF="#Transforming the Results">Transforming the Results</A>
   <A HREF="#Data Types">Data Types</A>
      <A HREF="#Data Type 1">Data Type 1</A>
         <A HREF="#Type 1 functions">Type 1 functions</A>
      <A HREF="#Data Type 2">Data Type 2</A>
         <A HREF="#Type 2 functions">Type 2 functions</A>
      <A HREF="#Data Type 3">Data Type 3</A>
         <A HREF="#Linear Interpolation Algorithm">Linear Interpolation Algorithm</A>
         <A HREF="#Type 3 functions">Type 3 functions</A>
      <A HREF="#Data Type 4">Data Type 4</A>
         <A HREF="#CK Type 4 pointing evaluation algorithm">CK Type 4 pointing evaluation algorithm</A>
         <A HREF="#Type 4 functions">Type 4 functions</A>
      <A HREF="#Data Type 5">Data Type 5</A>
         <A HREF="#Type 5 functions">Type 5 functions</A>
   <A HREF="#Appendix A --- Summary of C-kernel Functions">Appendix A --- Summary of C-kernel Functions</A>
      <A HREF="#Summary of Mnemonics">Summary of Mnemonics</A>
      <A HREF="#Summary of Calling Sequences">Summary of Calling Sequences</A>
   <A HREF="#Appendix B --- Example Program PLANET_POINT">Appendix B --- Example Program PLANET_POINT</A>
   <A HREF="#Appendix C --- An Example of Writing a Type 1 CK Segment">Appendix C --- An Example of Writing a Type 1 CK Segment</A>
   <A HREF="#Appendix D --- An Example of Writing a Type 2 CK Segment">Appendix D --- An Example of Writing a Type 2 CK Segment</A>
   <A HREF="#Appendix E --- An Example of Writing a Type 3 CK Segment">Appendix E --- An Example of Writing a Type 3 CK Segment</A>
   <A HREF="#Appendix G: Document Revision History">Appendix G: Document Revision History</A>
         <A HREF="#April 1, 2009">April 1, 2009</A>
         <A HREF="#November 17, 2005">November 17, 2005</A>
         <A HREF="#December 21, 2004">December 21, 2004</A>
         <A HREF="#February 2, 2004">February 2, 2004</A>
         <A HREF="#September 04, 2002">September 04, 2002</A>
         <A HREF="#February 15, 2000">February 15, 2000</A>
         <A HREF="#October 14, 1999">October 14, 1999</A>
         <A HREF="#Overview of the October 14, 1999 revision">Overview of the October 14, 1999 revision</A>

</PRE>

<HR SIZE=3 NOSHADE>

<BR><BR>
<A NAME="C-Kernel Required Reading"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> C-Kernel Required Reading
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   Last revised on 2010 JUN 03 by B. V. Semenov.
<P>
 
<BR><BR>
<A NAME="Abstract"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Abstract
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The C-kernel (CK) system is the component of SPICE concerned with
   attitude of spacecraft structures or instruments.
<P>
 
<BR><BR>
<A NAME="References"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> References
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   All references are to NAIF documents. The notation [Dn] refers to NAIF
   document number.
<P>
 
<UL>
<TT>1.</TT> [167] Double Precision Array Files Required Reading (<a href="../req/daf.html">daf.req</a>)
<BR><BR></UL>
<UL>
<TT>2.</TT> [349] FRAMES Required Reading (<a href="../req/frames.html">frames.req</a>).
<BR><BR></UL>
<UL>
<TT>3.</TT> [222] Spacecraft Clock Time Required Reading (<a href="../req/sclk.html">sclk.req</a>)
<BR><BR></UL>
<UL>
<TT>4.</TT> [214] Rotations Required Reading (<a href="../req/rotation.html">rotation.req</a>)
<BR><BR></UL>
<UL>
<TT>5.</TT> [211] SPC Required Reading: Comments in SPK and CK Files (<a href="../req/spc.html">spc.req</a>)
<BR><BR></UL>
<BR><BR>
<A NAME="DAF Run-Time Binary File Format Translation"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> DAF Run-Time Binary File Format Translation
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   Starting with the N0052 release of the SPICE Toolkit (January, 2002)
   certain supported platforms are able to read DAF-based binary files
   (SPK, CK and binary PCK) that were written using a different, or
   non-native, binary representation. This access is read-only; any
   operations requiring writing to the file (adding information to the
   comment area, or appending additional ephemeris data, for example)
   require prior conversion of the file to the native binary file format.
   See the Convert User's Guide, <a href="../ug/convert.html">convert.ug</a>, for details.
<P>
 
<BR><BR>
<A NAME="Detection of Non-native Text Files"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Detection of Non-native Text Files
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   Starting with the N0057 release of the SPICE Toolkit (March, 2004) the
   SPICE data loading mechanism detects and prohibits loading text kernel
   files containing lines terminated with EOF character(s) non-native to
   the platform on which the Toolkit was compiled. If a non-native EOL
   terminator is detected in the first 132 characters of a text kernel, the
   execution is stopped and an error message is displayed. This feature
   does not work with files that are smaller that 132 bytes or have the
   first line longer that 132 characters.
<P>
 
<BR><BR>
<A NAME="Introduction"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Introduction
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   In the SPICE system, pointing data for science instruments are stored in
   the C-kernel, the ``C'' in SPICE. The pointing of an instrument is often
   expressed in terms of a transformation matrix from some standard base
   reference frame to a local, instrument-fixed frame. In the past, the
   instrument was often a camera, and the transformation was thus dubbed
   the ``C-matrix''; hence the choice of C as the name for the pointing
   kernel.
<P>
 
   The data contained in C-kernel files can be accessed and manipulated by
   a collection of ANSI C functions which are part of the CSPICE library.
   These functions can be integrated into user application programs. The
   purpose of this document is to describe both the C-kernel file structure
   and the associated CSPICE software to the level of detail necessary for
   the user to program almost any application.
<P>
 
   With few exceptions, all functions appearing in this document are part
   of CSPICE or the standard ANSI C library. The exceptions are
   placeholders for user-supplied functions which appear in some of the
   code examples. Each CSPICE function is prefaced with a complete CSPICE
   header which describes inputs, outputs, restrictions and context, and
   provides examples of usage. The authoritative documentation for any
   function is its header, which should be consulted before using the
   function in any program. A summary of the CK functions presented in this
   document is included as Appendix A.
<P>
 
<BR><BR>
<A NAME="Preliminaries"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Preliminaries
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   In this chapter we discuss four concepts that are essential to using the
   C-kernel: specification of spacecraft and instruments, C-matrices,
   angular velocity vectors, and spacecraft clock time.
<P>
 
<BR><BR>
<A NAME="Specifying Spacecraft and Instruments"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Specifying Spacecraft and Instruments
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   C-kernel files and software use integer codes to refer to instruments
   and the spacecraft on which they are mounted. You will use these
   instrument numbers with C-kernel readers to request pointing data.
<P>
 
   In order to avoid confusion, NAIF, in cooperation with the science teams
   from each flight project, will assign instrument codes using the
   following scheme.
<P>
 
   If you're familiar with SPICE S- and P-kernels, you know that NAIF codes
   for spacecraft are negative integers: -31 for Voyager 1, -32 for Voyager
   2, -94 for Mars Global Surveyor, and so on. We borrow from this
   convention in defining instrument codes.
<P>
 
   For example, the Voyager 2 instruments could have been given these IDs:
<P>
 
<DL><DT>
<B>
 -32000
</B><BR><BR>
<DD>
 Instrument Scan Platform<BR>
</DL>
<DL><DT>
<B>
 -32001
</B><BR><BR>
<DD>
 ISSNA (Imaging science narrow angle camera)<BR>
</DL>
<DL><DT>
<B>
 -32002
</B><BR><BR>
<DD>
 ISSWA (Imaging science wide angle camera)<BR>
</DL>
<DL><DT>
<B>
 -32003
</B><BR><BR>
<DD>
 PPS (Photopolarimeter)<BR>
</DL>
<DL><DT>
<B>
 -32004
</B><BR><BR>
<DD>
 UVSAG (Ultraviolet Spectrometer, Airglow port)<BR>
</DL>
<DL><DT>
<B>
 -32005
</B><BR><BR>
<DD>
 UVSOCC (Ultraviolet Spectrometer, Occultation port)<BR>
</DL>
<DL><DT>
<B>
 -32006
</B><BR><BR>
<DD>
 IRIS (Infrared Interferometer Spectrometer and Radiometer)<BR>
</DL>
   The simple coding formula is
<P>
 
<PRE>
   SPICE s/c instrument code = (s/c code)*(1000) - instrument number
</PRE>
   which allows for 999 instruments on board any one spacecraft.
<P>
 
   The term ``instrument'' is used loosely throughout this document since
   the concept of orientation is applicable to structures other than just
   science instruments. For example, some of the Galileo instruments are in
   a fixed position relative to the scan platform. It might therefore be
   prudent to have a single file containing the orientation of the scan
   platform, and then produce the pointing for each of the scan platform
   science instruments by applying instrument offset angles obtained from
   the I-kernel.
<P>
 
<BR><BR>
<A NAME="C-Matrices"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> C-Matrices
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   A C-matrix is a 3x3 matrix that transforms Cartesian coordinates
   referenced to a ``base frame'' to coordinates in an instrument-fixed
   reference frame. In earlier versions of CSPICE, the base frame was
   required to be inertial; this restriction has been removed.
<P>
 
   The C-matrix transforms coordinates as follows: if a vector v has
   coordinates ( x, y, z ) in some base reference frame (like J2000), then
   v has coordinates ( x', y', z' ) in instrument-fixed coordinates, where
<P>
 
<PRE>
 
   [          ] [ x ]     [ x']
   | C-matrix | | y |  =  | y'|
   [          ] [ z ]     [ z']
 
</PRE>
   The transpose of a C-matrix rotates vectors from the instrument-fixed
   frame to the base frame:
<P>
 
<PRE>
 
   [          ]T [ x']     [ x ]
   | C-matrix |  | y'|  =  | y |
   [          ]  [ z']     [ z ]
 
</PRE>
   Therefore, if the coordinates of an instrument in the instrument fixed
   frame are known, then the transpose of the C-matrix can be used to
   determine the corresponding coordinates in a base reference frame. This
   information can be used to help answer questions such as, ``What is the
   latitude and longitude of the point on the planet that the camera was
   pointing at when it shuttered this picture?''
<P>
 
   The high-level CK file reader <a href="../cspice/ckgp_c.html">ckgp_c</a> ( Get Pointing ) returns a C-matrix
   that specifies the pointing of a spacecraft structure at a particular
   time. An example program is included in Appendix B, which solves the
   longitude and latitude problem presented above using <a href="../cspice/ckgp_c.html">ckgp_c</a> and other
   CSPICE functions.
<P>
 
<BR><BR>
<A NAME="Angular Velocity Vectors"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Angular Velocity Vectors
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   In the C-kernel an angular velocity vector is a vector with respect to a
   base frame whose direction gives the right-handed axis about which an
   instrument-fixed reference frame is rotating, and whose magnitude is
   equal to the magnitude of the rotation velocity, in radians per second.
<P>
 
   Angular rate information may be important for certain types of science
   analysis. For instance, investigators for imaging instruments might use
   angular rates to determine how much smear to expect in their images.
<P>
 
   CK files are capable of storing angular velocity data for instruments,
   although the presence of such data is optional. The CK reader <a href="../cspice/ckgpav_c.html">ckgpav_c</a>
   (Get Pointing and Angular Velocity) returns an angular velocity vector
   in addition to a C-matrix.
<P>
 
<BR><BR>
<A NAME="Spacecraft Clock Time"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Spacecraft Clock Time
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   Each piece of data within the C-kernel is associated with a spacecraft
   clock time (SCLK). This is because the spacecraft clock time is
   typically appended to the telemetry data that is the source for pointing
   information.
<P>
 
   Within the SPICE system, SCLK is represented as an encoded double
   precision number. You will need this form when using CK reader functions
   to read from CK files.
<P>
 
   CSPICE includes functions to convert between character SCLK format and
   the double precision encoding. There are also functions to convert
   between SCLK and standard time systems such as ET and UTC.
<P>
 
   The SCLK Required Reading, <a href="../req/sclk.html">sclk.req</a>, contains a full description of SCLK
   including the clock formats for individual spacecraft. You should read
   that document before writing any C-kernel programs. A brief description
   of SCLK is included here because many of the functions presented require
   a clock time as an input argument.
<P>
 
<BR><BR>
<A NAME="Encoded SCLK"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Encoded SCLK
</H3><P><BR><BR>
   Encoded SCLK values may be discrete or continuous.
<P>
 
   Discrete encoded SCLK values have units of ``ticks''; ticks represent
   the least significant counts representable by a clock. Continuous
   encoded SCLK supports non-integral tick values. This enables translation
   of other time systems to encoded SCLK without rounding.
<P>
 
   Throughout this document, encoded SCLK should be assumed to be
   continuous unless otherwise specified.
<P>
 
   To convert from a character string representation of SCLK to its double
   precision encoding, use the function <a href="../cspice/scencd_c.html">scencd_c</a> (Encode SCLK):
<P>
 
<PRE>
   <a href="../cspice/scencd_c.html">scencd_c</a> ( sc, sclkch, &amp;sclkdp );
</PRE>
   Use <a href="../cspice/scdecd_c.html">scdecd_c</a> (Decode SCLK) to recover the character representation from
   its double precision encoding.
<P>
 
<PRE>
   <a href="../cspice/scdecd_c.html">scdecd_c</a> ( sc, sclkdp, lenout, sclkch );
</PRE>
   The first argument to both functions, `sc', is the NAIF integer ID for
   the spacecraft whose clock count is being encoded or decoded (for
   example, -77 for Galileo).
<P>
 
   Above, the argument `lenout' is used by the caller to indicate the
   available space in the output string.
<P>
 
   Each spacecraft may have a different format for its clock counts, so the
   encoding scheme may be different for each. The SCLK Required Reading,
   <a href="../req/sclk.html">sclk.req</a>, indicates the expected clock string formats for each mission.
<P>
 
   To convert from ET to continuous encoded SCLK, use <a href="../cspice/sce2c_c.html">sce2c_c</a> (ET to
   continuous SCLK):
<P>
 
<PRE>
   <a href="../cspice/sce2c_c.html">sce2c_c</a> ( sc, sclkch, &amp;sclkdp );
</PRE>
   To convert continuous encoded SCLK to ET, use <a href="../cspice/sct2e_c.html">sct2e_c</a> (Ticks to ET):
<P>
 
<PRE>
   <a href="../cspice/sct2e_c.html">sct2e_c</a> ( sc, sclkdp, &amp;et );
</PRE>
<BR><BR>
<A NAME="Ticks and Partitions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Ticks and Partitions
</H3><P><BR><BR>
   The units of encoded SCLK are ``ticks since clock start at launch,''
   where a ``tick'' is defined to be the shortest time increment
   expressible by a particular spacecraft clock.
<P>
 
   The problem of encoding SCLK is complicated by the fact that spacecraft
   clocks do not always advance continuously. A discontinuity may occur if
   a clock resets to a different value. This occurs when a clock reaches
   its maximum value, but it can also happen due to other reasons which
   will not be discussed here. Anytime this occurs, we say that the clock
   has entered a new ``partition.''
<P>
 
   SCLK strings should normally include a partition number prefixed to the
   rest of the clock count with a ``/''. The partition number uniquely
   separates a count from identical counts in other partitions.
<P>
 
   The presence of the partition number is not required. If it is missing,
   <a href="../cspice/scencd_c.html">scencd_c</a> will assume the partition to be the earliest possible one
   containing the clock string.
<P>
 
<BR><BR>
<A NAME="SCLK and other time systems"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> SCLK and other time systems
</H3><P><BR><BR>
   CSPICE contains functions that convert between both the encoded and
   character form of spacecraft clock time and two other time systems.
<P>
 
   The first is ephemeris time (ET), which is specified as some number of
   ephemeris seconds past a reference epoch. Within the SPICE system, state
   vectors of spacecraft and target bodies are referenced to ET seconds
   past the J2000 epoch.
<P>
 
   The other is Coordinated Universal Time (UTC), which is also called
   Greenwich Mean Time. Two function calls are necessary to convert between
   UTC and SCLK. One function converts from SCLK to ET, and another from ET
   to UTC.
<P>
 
   See Appendix A for a list of high level functions involved in spacecraft
   clock time conversions.
<P>
 
<BR><BR>
<A NAME="The SCLK kernel file"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> The SCLK kernel file
</H3><P><BR><BR>
   Before calling any of the SCLK conversion functions mentioned above, you
   have to load the contents of the SCLK kernel file into the kernel pool,
   using the function <a href="../cspice/furnsh_c.html">furnsh_c</a>.
<P>
 
   The SCLK kernel file contains spacecraft specific parameters needed to
   perform the conversions. Included are such things as clock format
   definitions, partition start and stop times, and time interpolation
   constants. You should make sure that the kernel file you are using
   contains information for the particular spacecraft you are working with.
<P>
 
   You also have to load the leapseconds kernel file into the kernel pool
   if you are going to convert between ET and UTC.
<P>
 
<BR><BR>
<A NAME="Basics"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Basics
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   This chapter will present the easiest way to use C-kernel software to
   obtain pointing data from a CK file for a particular instrument. The
   mechanism for doing so is a ``reader,'' a function which reads data from
   the C-kernel. The highest level readers will be discussed here; one that
   returns the C-matrix, and another that returns the C-matrix and angular
   velocity vector.
<P>
 
   A later chapter will present lower level functions that allow the
   programmer to exert the highest amount of control in reading CK files.
<P>
 
   Appendix B contains an example showing how some of the functions
   presented in this chapter fit together in a typical application program.
<P>
 
<BR><BR>
<A NAME="The CK File Reader ckgp_c"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> The CK File Reader <a href="../cspice/ckgp_c.html">ckgp_c</a>
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   Below is a code fragment illustrating the use of the C-kernel file
   reader <a href="../cspice/ckgp_c.html">ckgp_c</a> (Get Pointing). The example finds the C-matrix for the
   Voyager 2 narrow angle camera at a particular epoch during the Jupiter
   encounter. The C-matrix returned is a transformation from the J2000
   frame to instrument-fixed coordinates.
<P>
 
   Each of the functions used is briefly described below. See the
   individual function headers for a complete description.
<P>
 
   A complete description of how <a href="../cspice/ckgp_c.html">ckgp_c</a> searches for pointing is provided
   in the ``Details'' chapter of this document.
<P>
 
<PRE>
      #include "SpiceUsr.h"
 
      SpiceBoolean            found;
 
      SpiceChar             * ref;
 
      SpiceDouble             clkout;
      SpiceDouble             cmat[3][3];
      SpiceDouble             sclkdp;
      SpiceDouble             tol;
 
      SpiceInt                inst;
      SpiceInt                sc;
 
      /*
      NAIF ID numbers for the
 
         1. Voyager 2 spacecraft
         2. Voyager 2 narrow angle camera
 
      */
      sc    =  -32;
      inst  =  -32001;
 
      /*
      The C-matrix should transform from J2000 to camera-fixed
      coordinates.
      */
      ref  =  "J2000";
 
      /*
      Load the spacecraft clock partition kernel file into the
      kernel pool, for SCLK encoding and decoding.
      */
      <a href="../cspice/furnsh_c.html">furnsh_c</a> ( "vgr2_sclk.tsc" );
 
      /*
      Load the C-kernel pointing file.
      */
      <a href="../cspice/furnsh_c.html">furnsh_c</a> ( "vgr2_jup_inbound.bc" );
 
      /*
      We want pointing at a spacecraft clock time appearing in
      the third spacecraft clock partition.
      */
      <a href="../cspice/scencd_c.html">scencd_c</a> ( sc, "3/20556:17:768", &amp;sclkdp );
 
      /*
      The Voyager 2 clock is of the form xxxxx yy www, where
      yy is a modulus 60 counter.  Pictures were not shuttered
      at intervals smaller than one mod 60 count.  Therefore,
      use this as the tolerance.  ( Notice that no partition
      number is used when specifying a tolerance )
      */
      <a href="../cspice/sctiks_c.html">sctiks_c</a> ( sc, "0:01:000", &amp;tol );
 
      /*
      Get the pointing for the narrow angle camera.
      */
      <a href="../cspice/ckgp_c.html">ckgp_c</a> ( inst, sclkdp, tol, ref, cmat, &amp;clkout, &amp;found );
</PRE>
<BR><BR>
<A NAME="furnsh_c"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> <a href="../cspice/furnsh_c.html">furnsh_c</a>
</H3><P><BR><BR>
   <a href="../cspice/furnsh_c.html">furnsh_c</a> loads the kernel pool with the contents of the specified text
   kernel file, which, in this case is the SCLK kernel file.
<P>
 
   <a href="../cspice/scencd_c.html">scencd_c</a> (below) and <a href="../cspice/scdecd_c.html">scdecd_c</a> require the contents of the SCLK kernel
   file in order to properly encode and decode clock values. (See section
   on Spacecraft Clock Time).
<P>
 
   <a href="../cspice/furnsh_c.html">furnsh_c</a> also loads a CK file for processing by other CK functions. It
   takes as input the name of the C-kernel file to be used, in this example
<P>
 
<PRE>
   "vgr2_jup_inbound.bc"
</PRE>
   Once loaded, a file is ready for any number of reads, so it needs to be
   loaded only once, typically in the initialization section of your
   program. Among other things, the lower level routines called by <a href="../cspice/furnsh_c.html">furnsh_c</a>
   open the file with all the appropriate options, relieving you of that
   responsibility.
<P>
 
<BR><BR>
<A NAME="scencd_c and sce2c_c"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> <a href="../cspice/scencd_c.html">scencd_c</a> and <a href="../cspice/sce2c_c.html">sce2c_c</a>
</H3><P><BR><BR>
   <a href="../cspice/scencd_c.html">scencd_c</a> encodes a character representation of spacecraft clock time
   such as
<P>
 
<PRE>
   "3/20556:17:768"
</PRE>
   into a double precision number (sclkdp). The value returned by <a href="../cspice/scencd_c.html">scencd_c</a>
   is a discrete tick count. When starting with an ET value, a continuous
   tick count may be obtained by calling <a href="../cspice/sce2c_c.html">sce2c_c</a>.
<P>
 
   You must use encoded SCLK when calling CK reader functions.
<P>
 
<BR><BR>
<A NAME="sctiks_c"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> <a href="../cspice/sctiks_c.html">sctiks_c</a>
</H3><P><BR><BR>
   <a href="../cspice/sctiks_c.html">sctiks_c</a> converts a clock string without partition number to units of
   ``ticks,'' which are the units of encoded SCLK returned by <a href="../cspice/scencd_c.html">scencd_c</a>.
<P>
 
   The distinction between <a href="../cspice/scencd_c.html">scencd_c</a> and <a href="../cspice/sctiks_c.html">sctiks_c</a> is important. The result
   of calling <a href="../cspice/scencd_c.html">scencd_c</a> is a relative measurement: ticks since the start of
   the clock at launch. The result of calling <a href="../cspice/sctiks_c.html">sctiks_c</a> is an absolute
   measurement: ticks. It's like the difference between the times 3:55 p.m.
   (a specific time of the day) and 3:55 (three hours and fifty-five
   minutes - a length of time).
<P>
 
<BR><BR>
<A NAME="ckgp_c"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> <a href="../cspice/ckgp_c.html">ckgp_c</a>
</H3><P><BR><BR>
   <a href="../cspice/ckgp_c.html">ckgp_c</a> looks through files loaded by <a href="../cspice/furnsh_c.html">furnsh_c</a> to find the data needed to
   compute the C-matrix for a specified spacecraft instrument at a
   particular time. It uses the following inputs and outputs.
<P>
 
   Inputs are:
<P>
 
<DL><DT>
<B>
 `inst'
</B><BR><BR>
<DD>
 The NAIF instrument ID. In this example, we want pointing for the
Voyager 2 narrow angle camera (NAIF code -32001).<BR>
</DL>
<DL><DT>
<B>
 `sclkdp'
</B><BR><BR>
<DD>
 Encoded SCLK time. Units are ``ticks since clock start at launch'' May
be discrete or continuous.<BR>
</DL>
<DL><DT>
<B>
 `tol'
</B><BR><BR>
<DD>
 SCLK time tolerance. `tol' is measured in units of ``ticks.''<BR>
</DL>
<DL><DT>
<DD>
 The pointing returned by <a href="../cspice/ckgp_c.html">ckgp_c</a> will be for a time within `tol' ticks
of `sclkdp'. In general, `tol' should be smaller than the typical
spacecraft clock time interval between instrument observations.<BR>
</DL>
<DL><DT>
<B>
 `ref'
</B><BR><BR>
<DD>
 The NAIF mnemonic for the base reference frame. The output C-matrix, if
found, will be a transformation from `ref' to instrument-fixed
coordinates.<BR>
</DL>
<DL><DT>
<DD>
 See the FRAMES Required Reading, <a href="../req/frames.html">frames.req</a>, for a list of those frames
supported by the SPICE system, along with the accepted mnemonics for
those frames.<BR>
</DL>
   Outputs are:
<P>
 
<DL><DT>
<B>
 `cmat'
</B><BR><BR>
<DD>
 The C-matrix. `cmat' is a transformation matrix from the base frame
`ref' to the instrument-fixed frame at the time `clkout'.<BR>
</DL>
<DL><DT>
<B>
 `clkout'
</B><BR><BR>
<DD>
 Continuous encoded spacecraft clock time for which `cmat' is valid.
This will be within `tol' ticks of `sclkdp'.<BR>
</DL>
<DL><DT>
<B>
 `found'
</B><BR><BR>
<DD>
 Found flag. `found' will be true if it was possible to return a
C-matrix for `inst' for a time within `tol' ticks of `sclkdp'. `found'
will be false otherwise.<BR>
</DL>
<BR><BR>
<A NAME="The CK File Reader ckgpav_c"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> The CK File Reader <a href="../cspice/ckgpav_c.html">ckgpav_c</a>
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   <a href="../cspice/ckgpav_c.html">ckgpav_c</a> (Get Pointing and Angular Velocity) is almost identical to
   <a href="../cspice/ckgp_c.html">ckgp_c</a>, except that it returns an angular velocity vector in addition to
   a C-matrix.
<P>
 
   The calling sequence for <a href="../cspice/ckgpav_c.html">ckgpav_c</a> is:
<P>
 
<PRE>
   <a href="../cspice/ckgpav_c.html">ckgpav_c</a> ( inst, sclkdp, tol, ref, cmat, av, &amp;clkout, &amp;found );
</PRE>
   The angular velocity vector `av' is a double precision array of size
   three. The components of `av' are given relative to the base reference
   frame `ref'.
<P>
 
   All of the other arguments are identical to those of <a href="../cspice/ckgp_c.html">ckgp_c</a>. And, just
   as with <a href="../cspice/ckgp_c.html">ckgp_c</a>, you must load a CK file by calling <a href="../cspice/furnsh_c.html">furnsh_c</a> before
   calling <a href="../cspice/ckgpav_c.html">ckgpav_c</a>.
<P>
 
   The behavior of <a href="../cspice/ckgpav_c.html">ckgpav_c</a> is, however, slightly different from that of
   <a href="../cspice/ckgp_c.html">ckgp_c</a>, and these differences will be explained in the ``Details''
   chapter of this document.
<P>
 
<BR><BR>
<A NAME="Multiple Files and the C-kernel"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Multiple Files and the C-kernel
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   There will probably be occasions when you will want to access pointing
   that is contained in more than one CK file. For instance, you may have
   several files describing pointing for several disjoint time periods, or
   for different instruments. Or you may have one file containing a
   partially updated version of another file's pointing.
<P>
 
   In both cases, you would like to be able to get the pointing you want
   without having to run your application on each file separately. C-kernel
   software allows you to do this through the file loading and unloading
   process.
<P>
 
   The file loading function <a href="../cspice/furnsh_c.html">furnsh_c</a> was introduced in the last section.
   It was mentioned that you have to load the CK file before you try to
   access it, that you have to load it only once during program execution,
   and that in subsequent calls to <a href="../cspice/ckgp_c.html">ckgp_c</a>, you don't have to refer to the
   file at all.
<P>
 
   What was not mentioned was that multiple pointing files may be loaded
   and that <a href="../cspice/ckgp_c.html">ckgp_c</a> will automatically search through as many of the files
   as necessary to satisfy the request.
<P>
 
   If you have multiple files describing pointing for different time
   periods or different instruments, you can simply load them all at the
   beginning of your program, and then forget about which file covered what
   period or instrument. There is a hierarchy for searching, however, that
   you need to understand in case you happen to load files that have
   redundant coverage.
<P>
 
   A request for pointing is satisfied by searching through the last loaded
   files first. Thus if we ran
<P>
 
<PRE>
   <a href="../cspice/furnsh_c.html">furnsh_c</a> ( "ckfile_1.bc" );
   <a href="../cspice/furnsh_c.html">furnsh_c</a> ( "ckfile_2.bc" );
   <a href="../cspice/furnsh_c.html">furnsh_c</a> ( "ckfile_3.bc" );
</PRE>
   and then later made a request for pointing, the software would search
   through ckfile_3 first, ckfile_2 second, and ckfile_1 last.
<P>
 
   This scheme is consistent with the fact that within an individual file,
   the data that were inserted last supersede those before them. In
   essence, loaded files are treated like one big file.
<P>
 
   What if you have files representing different versions of the same
   pointing? This is a likely scenario considering there are tools (such as
   NAIF's C-smithing program) to update and ``improve'' pointing results.
<P>
 
   For example, suppose you have one file containing predicted pointing
   values, and another containing improved, updated values. One approach
   would be to load the files in the following order:
<P>
 
<PRE>
   <a href="../cspice/furnsh_c.html">furnsh_c</a> ( "predict.bc" );
   <a href="../cspice/furnsh_c.html">furnsh_c</a> ( "update.bc"  );
</PRE>
   This way, the ``better'' (updated) pointing file always gets searched
   first.
<P>
 
   If, on the other hand, you want to be explicit about which file to
   search, you need a way of telling C-kernel software to stop looking in
   one file, and start looking in another. <a href="../cspice/furnsh_c.html">furnsh_c</a> accomplishes the latter
   by loading a file for processing. To tell C-kernel software to stop
   looking through a file, then, you need to unload it, with <a href="../cspice/unload_c.html">unload_c</a> :
<P>
 
<PRE>
      #include "SpiceUsr.h"
 
      /*
      Load the first version.
      */
      <a href="../cspice/furnsh_c.html">furnsh_c</a> ( "predict.bc" );
 
         .
         .  process pointing from first file.
         .
 
      /*
      Unload the first version.
      */
      <a href="../cspice/unload_c.html">unload_c</a> ( "predict.bc" );
 
      /*
      Load the second version.
      */
      <a href="../cspice/furnsh_c.html">furnsh_c</a> ( "update.bc" );
 
         .
         .  process pointing from the second file.
         .
 
</PRE>
<BR><BR>
<A NAME="CK Coverage Summary Routines"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> CK Coverage Summary Routines
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The CSPICE includes two functions for obtaining information about the
   contents of a CK file from within an application.
<P>
 
   The <a href="../cspice/ckobj_c.html">ckobj_c</a> function provides an API via which an application can find
   the set of instruments for which a specified CK file contains data. The
   instrument IDs are returned in a SPICE ``set'' data structure (see
   <a href="../req/sets.html">sets.req</a>).
<P>
 
   The <a href="../cspice/ckcov_c.html">ckcov_c</a> function provides an API via which an application can find
   the time periods for which a specified CK file provides data for an
   instrument of interest. The coverage information is a set of disjoint
   time intervals returned in a SPICE ``window'' data structure (see
   <a href="../req/windows.html">windows.req</a>).
<P>
 
   Refer to the headers of <a href="../cspice/ckobj_c.html">ckobj_c</a> and <a href="../cspice/ckcov_c.html">ckcov_c</a> for details on the use of
   those routines.
<P>
 
<BR><BR>
<A NAME="Details"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Details
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   In the previous chapter, we introduced the two CK readers, <a href="../cspice/ckgp_c.html">ckgp_c</a> and
   <a href="../cspice/ckgpav_c.html">ckgpav_c</a>, which return C-matrices and angular velocity vectors from CK
   files.
<P>
 
   In this chapter we introduce the concept of a CK file segment, and
   explain how these segments are organized into CK files. We then show
   exactly how <a href="../cspice/ckgp_c.html">ckgp_c</a> and <a href="../cspice/ckgpav_c.html">ckgpav_c</a> go about searching through files and
   segments to obtain the data that they need.
<P>
 
<BR><BR>
<A NAME="File Structure and Implementation"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> File Structure and Implementation
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   Each C-kernel file is made up of a number of ``segments.'' A segment is
   a set of logical records containing double precision numbers. When
   evaluated, each record gives a C-matrix and optionally, an angular
   velocity vector, of some spacecraft structure for some time within an
   interval. The segments in a file are ordered from beginning to end, with
   new segments added to the end of a file. The C-kernel readers use this
   ordering to check segments at the end of the file first.
<P>
 
   Notice that the definition of a segment does not specify what type of
   record it contains. This vagueness is intentional. One of the primary
   features of the C-kernel is to provide a framework in which to store
   pointing data in any form, without users having to worry about that form
   when reading the data. Thus, different segments may contain different
   implementations of discrete or continuous data, but the same high-level
   readers are used to access all types.
<P>
 
   In fact, there are only a couple of functions that are concerned with
   the internal data type of a segment. Other functions obtain all the
   information they need about a segment from two fields which precede each
   segment: ``descriptors'' and ``identifiers.'' Their formats are
   identical from segment to segment, and provide important information
   about the data contained inside.
<P>
 
<BR><BR>
<A NAME="Segment Descriptors"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Segment Descriptors
</H3><P><BR><BR>
   The C-kernel reader functions begin addressing the question, ``Can the
   request for pointing be satisfied by this segment?'' by looking at the
   descriptor.
<P>
 
   A descriptor tells what instrument's pointing is being described, the
   interval of time for which the segment is valid, the reference frame of
   the internally stored data, and the segment data type.
<P>
 
   Each segment descriptor contains two double precision components (DCD)
   and six integer components (ICD).
<P>
 
<PRE>
           -----------------------------------
   DCD(1)  |  Initial SCLK                   |
           -----------------------------------
   DCD(2)  |  Final SCLK                     |
           -----------------------------------
   ICD(1)  |  Instrument    |
           ------------------
   ICD(2)  |  Reference     |
           ------------------
   ICD(3)  |  Data type     |
           ------------------
   ICD(4)  |  Rates Flag    |
           ------------------
   ICD(5)  |  Begin Address |
           ------------------
   ICD(6)  |  End   Address |
           ------------------
</PRE>
<DL><DT>
<B>
 DCD(1),<BR> DCD(2)
</B><BR><BR>
<DD>
 The initial and final encoded spacecraft clock times for the segment.<BR>
</DL>
<DL><DT>
<B>
 ICD(1)
</B><BR><BR>
<DD>
 The integer code of the instrument whose pointing is being described.<BR>
</DL>
<DL><DT>
<B>
 ICD(2)
</B><BR><BR>
<DD>
 The NAIF integer ID of the base reference frame for the segment data.
(For example, J2000, B1950, and so on --- to see which ID represents
which coordinate system, see the Frames Required Reading, <a href="../req/frames.html">frames.req</a>.)<BR>
</DL>
<DL><DT>
<B>
 ICD(3)
</B><BR><BR>
<DD>
 The data type of the segment. This indicates how the data is stored
internally. The reader functions will use it to evaluate the data
records. Typically, users will not have to know this code.<BR>
</DL>
<DL><DT>
<B>
 ICD(4)
</B><BR><BR>
<DD>
 The angular rates flag. This indicates whether or not the segment is
capable of producing angular velocity data. If ICD(4) = 0, then the
segment contains pointing data only. If ICD(4) = 1, then the segment
contains angular velocity data as well.<BR>
</DL>
<DL><DT>
<B>
 ICD(5),<BR> ICD(6)
</B><BR><BR>
<DD>
 Initial and final addresses of the segment data within the file. Users
will typically not want or need to know about these addresses. They
tell the readers where to go within a file to get the records needed to
satisfy a particular request.<BR>
</DL>
   The descriptor is stored as a double precision array, with pairs of
   integer components equivalenced to double precision numbers. We say that
   the descriptor is ``packed'' into a double precision array. The size of
   a packed descriptor is five double precision numbers.
<P>
 
   In the ``Looking at Descriptors'' section, you will be shown how to get
   a descriptor from a particular segment and ``unpack'' it into its double
   precision and integer components. You can then view the individual
   components.
<P>
 
<BR><BR>
<A NAME="Segment Identifiers"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Segment Identifiers
</H3><P><BR><BR>
   The idea behind a segment identifier is to provide a character field
   which allows a user to determine the exact origin of the segment.
<P>
 
   For the most part, it will be up to the institution that creates a
   particular C-kernel segment to determine what goes in this free-format
   40 character memory cell. However, it should be possible for users to
   look at a segment identifier and determine who knows the details about
   the creation of the segment.
<P>
 
   For example, if a particular identifier looked like
<P>
 
<PRE>
   NAIF CSMITHING RET LOGA151
</PRE>
   then a user should be able to contact NAIF to locate the right people to
   give the history of that segment: ephemerides used, source of pointing,
   assumptions, constraints, and so on.
<P>
 
   Forty characters is not enough space to store all source information for
   every segment that might be built. Instead, the idea is to provide a
   pointer to the people or documents that will have all of the details
   about the source of the data.
<P>
 
<BR><BR>
<A NAME="Comment Area"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Comment Area
</H3><P><BR><BR>
   In addition to segment identifiers, every binary CK file has a ``Comment
   Area'' for storing free-format textual information about the pointing
   data in the file. Ideally, each CK file will contain internal
   documentation that describes all of the details about the source of the
   data, its recommended use, and any other pertinent information. For
   example, the beginning and ending epochs for the file, the names and
   NAIF integer codes of the instruments included, an accuracy estimate,
   the date the file was produced, the names of the ephemeris files used,
   and any assumptions or constraints could be included. Comments about a
   particular segment in the file could refer to the segment by its
   identifier.
<P>
 
   CSPICE provides a family of functions for handling this Comment Area.
   The name of each function in this family begins with the letters
   ```spc''' which stand for ```spk' and `ck''' because this feature is
   common to both types of files. The SPC software provides the ability to
   add, extract, and delete comments and convert commented files from
   binary format to SPICE transfer format and back to binary again.
<P>
 
   The SPC functions and their purposes are described in detail in the SPC
   Required Reading, <a href="../req/spc.html">spc.req</a>.
<P>
 
<BR><BR>
<A NAME="A CK file is a DAF"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> A CK file is a DAF
</H3><P><BR><BR>
   Each CK file is one implementation of a NAIF construct called a Double
   Precision Array File (DAF). DAFs are described in detail in reference
   [1]. Each CK segment is an instance of the DAF double precision array.
   The descriptor is an instance of a DAF ``summary''; the identifier is an
   instance of a DAF ``name.''
<P>
 
   DAF functions are used at the lowest level to open, close, read, write
   and search CK files. As such, they allow for maximum flexibility in, for
   instance, examining a particular number within a segment, or searching
   for a particular segment within a file. Therefore, if the CK functions
   presented in this document do not allow you the control you want in
   looking through files, the DAF functions certainly will.
<P>
 
<BR><BR>
<A NAME="SPICE File Identification Word in CK Files"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> SPICE File Identification Word in CK Files
</H3><P><BR><BR>
   The SPICE file identification word occupying the first eight bytes of a
   properly created binary CK file is ``DAF/CK ''. For more information on
   SPICE file identification words refer to the Kernel Required Reading
   document, <a href="../req/kernel.html">kernel.req</a>.
<P>
 
<BR><BR>
<A NAME="How the CK Readers Work"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> How the CK Readers Work
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   There are basically two steps to reading data from the C-kernel:
   locating the segment applicable to the request made, and evaluating the
   data contained inside the segment to return the C-matrix and angular
   velocity vector. In this section you'll see how these steps are
   implemented by <a href="../cspice/ckgp_c.html">ckgp_c</a> and <a href="../cspice/ckgpav_c.html">ckgpav_c</a>.
<P>
 
<BR><BR>
<A NAME="The General Search Algorithm"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> The General Search Algorithm
</H3><P><BR><BR>
   The CK readers search through files loaded by <a href="../cspice/furnsh_c.html">furnsh_c</a> to satisfy a
   pointing request. The files are searched in the reverse order from which
   they were loaded. Thus the last-loaded file is searched first, then the
   second to last, and so forth. The contents of individual files are also
   searched in backwards order, giving priority to segments that were added
   to a file later than the others.
<P>
 
   The search ends when a segment is found that can give pointing for the
   specified instrument at a time falling within the specified tolerance on
   either side of the request time. Within that segment, the instance
   closest to the input time is located and returned.
<P>
 
   The time for which pointing is being returned is not always the closest
   to the request time in all of the loaded files. The returned time is
   actually the closest time within the tolerance of the request time from
   the first segment that can satisfy the request. The algorithm works like
   this because it assumes that the last loaded files contain the highest
   quality pointing. Because segments are prioritized in this way users
   should not make their tolerance argument larger than the minimum spacing
   between the data in the files they are reading.
<P>
 
   The following example illustrates this search procedure. Segments A and
   B are in the same file, with segment A located closer to the end of the
   file than segment B. Both segments A and B contain discrete pointing
   data.
<P>
 
<PRE>
 
                                 SCLKDP    TOL
                                      \   /
                                       | |
                                       |/ \
        Request 1                  [---+---]
                                   .   .   .
                                   .   .   .
        Segment A          (0-----------------0--------0--0-----0)
                                   .   .   .
                                   .   .   .
        Segment B         (-0--0--0--0--0--0--0--0--0--0--0--0--0)
                                        ^
                                        |
                          CK reader returns this instance
 
 
 
                                      SCLKDP
                                           \   TOL
                                            | /
                                            |/\
        Request 2                        [--+--]
                                         .  .  .
                                         .  .  .
        Segment A          (0-----------------0--------0--0-----0)
                                              ^
                                              |
                                CK reader returns this instance
 
        Segment B         (0-0--0--0--0--0--0--0--0--0--0--0--0-0)
 
</PRE>
   Segments that contain continuous pointing data are searched in the same
   manner as discrete segments. For request times that fall within the
   bounds of continuous intervals, the CK reader will return pointing at
   the request time. When the request time does not fall within an
   interval, then a time at an endpoint of an interval may be returned if
   it is the closest time in the segment to the user request time and also
   within the tolerance.
<P>
 
   In the following examples segment A contains discrete pointing data and
   segment C contains continuous data. Segment A is located closer to the
   end of the file than segment C.
<P>
 
<PRE>
                            SCLKDP
                                 \  TOL
                                  | /
                                  |/\
   Request 3                   [--+--]
                               .  .  .
                               .  .  .
   Segment A          (0-----------------0--------0--0-----0)
                               .  .  .
                               .  .  .
   Segment C          (--[=============]---[====]------[=]--)
                                  ^
                                  |
                     CK reader returns this instance
 
</PRE>
   In the next example assume that the order of segment A and C in file are
   reversed.
<P>
 
<PRE>
                                   SCLKDP
                                        \   TOL
                                         | /
                                         |/\
   Request 4                          [--+--]
                                      .  .  .
                                      .  .  .
   Segment C          (--[=============]---[====]------[=]--)
                                           ^
                                           |
                             CK reader returns this instance
 
   Segment A          (0-----------------0--------0--0-----0)
                                         ^
                                         |
                                   "Best" answer
 
</PRE>
   The next example illustrates an unfortunate side effect of using a
   non-zero tolerance when reading multi-segment CKs with continuous data.
   In all cases when the look-up interval formed using tolerance overlaps a
   segment boundary and the request time falls within the coverage of the
   lower priority segment, the data at the end of the higher priority
   segment will be picked instead of the data from the lower priority
   segment.
<P>
 
<PRE>
                                           SCLKDP
                                          /
                                         |  TOL
                                         | /
                                         |/\
   Your request                       [--+--]
                                      .  .  .
                                      .  .  .
   Segment C                                (===============)
                                            ^
                                            |
                              CK reader returns this instance
 
   Segment A          (=====================)
                                         ^
                                         |
                                   "Best" answer
</PRE>
   In general, because using a non-zero tolerance affects selection of the
   segment from which the data is obtained, users are strongly discouraged
   from using a non-zero tolerance when reading CKs with continuous data.
   Using a non-zero tolerance should be reserved exclusively to reading CKs
   with discrete data because in practice obtaining data from such CKs
   using a zero tolerance is often not possible due to time round off.
<P>
 
   The next few sections will go into greater detail about how <a href="../cspice/ckgp_c.html">ckgp_c</a> and
   <a href="../cspice/ckgpav_c.html">ckgpav_c</a> search through segments.
<P>
 
<BR><BR>
<A NAME="The Difference Between ckgp_c and ckgpav_c"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> The Difference Between <a href="../cspice/ckgp_c.html">ckgp_c</a> and <a href="../cspice/ckgpav_c.html">ckgpav_c</a>
</H3><P><BR><BR>
   The only significant difference between the search algorithms of <a href="../cspice/ckgp_c.html">ckgp_c</a>
   and <a href="../cspice/ckgpav_c.html">ckgpav_c</a> is in which segments they search through to satisfy a
   request for pointing data. Recall that segments in a CK file only
   optionally contain angular velocity data. Since <a href="../cspice/ckgp_c.html">ckgp_c</a> does not return
   an angular velocity vector, it is free to consider all segments when
   satisfying a request, because all segments will contain the data for
   constructing C-matrices. <a href="../cspice/ckgpav_c.html">ckgpav_c</a>, on the other hand, will consider only
   those segments which also contain angular velocity data.
<P>
 
   Because of this difference, it is possible that on the exact same set of
   inputs, <a href="../cspice/ckgp_c.html">ckgp_c</a> and <a href="../cspice/ckgpav_c.html">ckgpav_c</a> could return different values for the
   C-matrix. This could occur if a CK file contained two segments covering
   the same time period for the same instrument, one with angular rates and
   one without. <a href="../cspice/ckgp_c.html">ckgp_c</a> might use the C-matrix only segment, whereas
   <a href="../cspice/ckgpav_c.html">ckgpav_c</a> would ignore that segment and use the one containing angular
   velocity data.
<P>
 
   To avoid this situation, NAIF advises users not to place segments with
   and without angular velocity data in the same file.
<P>
 
<BR><BR>
<A NAME="Locating the Applicable Segment"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Locating the Applicable Segment
</H3><P><BR><BR>
   Within <a href="../cspice/ckgp_c.html">ckgp_c</a> and <a href="../cspice/ckgpav_c.html">ckgpav_c</a>, finding the right segment is the job of
   ckbss_ (Begin a Search for a Segment), and cksns_ (Select the Next
   Segment).
<P>
 
   The SPICELIB Fortran routines from which ckbss_ and cksns_ are derived
   are both entry points to the SPICELIB Fortran routine CKBSR (Buffer
   Segments for Readers).
<P>
 
   ckbss_ establishes a search for segments. It records the desired
   instrument (`inst'), SCLK time (`sclkdp'), and SCLK tolerance (`tol')
   for the search. It also records the need for angular velocity ---
   `needav' is true if angular velocity data is being requested, false
   otherwise.
<P>
 
   cksns_ then uses DAF functions to search through loaded files to find a
   segment matching the criteria established in the call to ckbss_.
   Last-loaded files get searched first, and within a single file, segments
   get checked starting from the end of the file and going backwards.
<P>
 
   When an applicable segment is found, the descriptor and identifier for
   that segment, and the handle of the file containing the segment, are
   returned, and the readers output Boolean flag `found' is set to true. If
   no applicable segment is found, `found' is false.
<P>
 
   If a segment is found, but is subsequently found to be inadequate,
   cksns_ can be called again to find the next applicable segment using the
   searching order described above.
<P>
 
   cksns_ can be called any number of times after a search has been started
   by ckbss_, and will just return a false value for `found' whenever
   applicable segments have run out.
<P>
 
   Because cksns_ is called every time a request is made, an internal
   buffer of segment descriptors is maintained by ckbsr_ to keep from
   performing superfluous file reads. You can adjust the size of the buffer
   by changing the parameter STSIZE in ckbsr_.
<P>
 
<BR><BR>
<A NAME="Looking at Descriptors"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Looking at Descriptors
</H3><P><BR><BR>
   The descriptor and handle returned by cksns_ are used by other CK
   functions to locate and evaluate the pointing records. In order to do
   so, those functions have to unpack a descriptor into its double
   precision and integer parts, using the DAF function <a href="../cspice/dafus_c.html">dafus_c</a> (Unpack
   Summary).
<P>
 
<BR><BR>
<A NAME="Evaluating the Records --- the Reader ckpfs_"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Evaluating the Records --- the Reader ckpfs_
</H3><P><BR><BR>
   After locating an appropriate segment via cksns_, <a href="../cspice/ckgp_c.html">ckgp_c</a> and <a href="../cspice/ckgpav_c.html">ckgpav_c</a>
   evaluate pointing records with a call to ckpfs_ (Pointing From Segment),
   a low level CK reader.
<P>
 
   ckpfs_ takes as input the handle and descriptor of the applicable file
   and segment, along with the time specifications and angular velocity
   flag.
<P>
 
   ckpfs_ returns the C-matrix and, if requested, the angular velocity
   vector for the time in the segment closest to `sclkdp' and within `tol'
   ticks of it. If ckpfs_ can't locate a time close enough in the segment,
   then `found' is set to false. (If `found' is false, then <a href="../cspice/ckgp_c.html">ckgp_c</a> and
   <a href="../cspice/ckgpav_c.html">ckgpav_c</a> will try another segment by calling cksns_ again, then ckpfs_
   again, and so on.)
<P>
 
   The output data are referenced to the base frame indicated by the
   descriptor. In other words, at this point, `cmat' is a transformation
   from the base frame specified by icd[1] to instrument-fixed coordinates,
   and the coordinates of `av' lie in that same base frame.
<P>
 
<BR><BR>
<A NAME="Transforming the Results"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Transforming the Results
</H3><P><BR><BR>
   The final task performed by <a href="../cspice/ckgp_c.html">ckgp_c</a> and <a href="../cspice/ckgpav_c.html">ckgpav_c</a> is to transform the
   returned data from their stored reference frame to that requested by the
   calling program.
<P>
 
   First, the functions compare the NAIF ID for the requested frame with
   that of the stored frame. If the requested frame matches the segment
   frame, there is nothing to be done. Otherwise, the C-matrix and angular
   velocity vector have to be transformed.
<P>
 
   Recall that the C-matrix returned by ckpfs_c is a rotation matrix from a
   base frame (call it `refseg') to instrument-fixed coordinates:
<P>
 
<PRE>
   [          ] I-fixed
   |          |
   |   CMAT   |
   |          |
   [          ] REFSEG
</PRE>
   What we want is a rotation matrix from the requested frame (call it
   `refreq') to instrument-fixed coordinates:
<P>
 
<PRE>
   [          ] I-fixed
   |          |
   |   CMAT   |
   |          |
   [          ] REFREQ
</PRE>
   So all we have to do is multiply the returned C-matrix by a rotation
   matrix, call it `rmat', from the requested frame to the one specified in
   the segment:
<P>
 
<PRE>
   [          ] I-fixed      [          ] I-fixed  [          ] REFSEG
   |          |              |          |          |          |
   |   CMAT   |          =   |   CMAT   |          |   RMAT   |
   |          |              |          |          |          |
   [          ] REFREQ       [          ] REFSEG   [          ] REFREQ
</PRE>
   Once you have `rmat', it is a trivial matter to transform the angular
   velocity vector. Its coordinates, upon return from ckpfs_, are in the
   frame `refseg'.
<P>
 
<BR><BR>
<A NAME="Data Types"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Data Types
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   The C-kernel framework for providing pointing data has been designed for
   flexibility. Different methods of storing and evaluating the data can be
   implemented independently of the high-level functions used to read the
   data. The only real restriction is that each segment must be stored as
   an array of double precision numbers.
<P>
 
   Each method of storing and evaluating the data contained in a segment
   defines a different ``data type.'' The data type of a segment is
   specified by the third integer component of the segment descriptor. The
   integer code for a data type is equal to the number of that type. For
   example, a segment of data type 1 would have the third integer component
   of its descriptor equal to 1. A data type need not accommodate angular
   velocity data. If it can't, all segments of that data type would have
   the value of the fourth integer component of the descriptor set equal to
   zero, which indicates that the segment does not contain angular velocity
   data.
<P>
 
   The CK reader that makes a distinction between segments of different
   data types is the low level reader CKPFS. The main body of CKPFS
   consists of a case statement of the form:
<P>
 
<PRE>
   if ( type == 1 )
   {
      .
      .
      .
   }
   else if ( type == 2 )
   {
      .
      .
      .
   }
   else if ( type == n )
   {
 
   }
   else
   {
      <a href="../cspice/setmsg_c.html">setmsg_c</a> ( "The data type # is not currently supported." );
      <a href="../cspice/errint_c.html">errint_c</a> ( "#", type                                     );
      <a href="../cspice/sigerr_c.html">sigerr_c</a> ( "SPICE(CKUNKNOWNDATATYPE)"                    );
   }
</PRE>
   Once ckpfs_ determines the data type of a segment, two type-specific
   functions are called. The first, ckrxx_, reads a segment of type xx and
   returns the information from the segment necessary to evaluate pointing
   at a particular time. The second function ckexx_ evaluates the
   information returned by ckrxx_, producing a C-matrix, and if requested,
   an angular velocity vector.
<P>
 
   There are currently four supported CK data types in CSPICE and they are
   described in detail in the sections that follow.
<P>
 
<BR><BR>
<A NAME="Data Type 1"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Data Type 1
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The following method of storing and evaluating discrete pointing and
   angular rate values defines C-kernel data type 1.
<P>
 
   Each pointing instance is stored as a four-tuple called a
   ``quaternion.'' Quaternions are widely used to represent rotation
   matrices. They require less than half the space of 3x3 matrices and
   finding the rotation matrix given by a quaternion is faster and easier
   than finding it from, say, RA, Dec, and Twist. In addition, other
   computations involving rotations, such as finding the rotation
   representing two successive rotations, may be performed on the
   quaternions directly.
<P>
 
   The four numbers of a quaternion represent a unit vector and an angle.
   The vector represents the axis of a rotation, and the angle represents
   the magnitude of that rotation. If the vector is U = (u1, u2, u3), and
   the angle is T, then the quaternion Q is given by:
<P>
 
<PRE>
        Q = ( q0, q1, q2, q3 )
          = ( cos(T/2), sin(T/2)*u1, sin(T/2)*u2, sin(T/2)*u3 )
</PRE>
   The details of quaternion representations of rotations, and the
   derivations of those representations are documented in the CSPICE
   Required Reading file ROTATIONS, <a href="../req/rotation.html">rotation.req</a>.
<P>
 
   Data type 1 provides the option of including angular velocity data. If
   such data is included, the angular velocity vector A = (a1, a2, a3 )
   corresponding to each pointing instance will be stored as itself. The
   coordinates of the vector will be in the same base reference frame as
   that of the C-matrix quaternions.
<P>
 
   A type 1 pointing record consists of either four or seven double
   precision numbers; four for the C-matrix quaternion, and, optionally,
   three for the angular velocity vector.
<P>
 
<PRE>
   +--------+--------+--------+--------+--------+--------+--------+
   |   q    |   q    |   q    |   q    |   a    |   a    |   a    |
   |    0   |    1   |    2   |    3   |    1   |    2   |    3   |
   +--------+--------+--------+--------+--------+--------+--------+
</PRE>
   Every type 1 segment has four parts to it:
<P>
 
<PRE>
   +----------------------------------------------------------------+
   |                                                                |
   |                                                                |
   |                           Pointing                             |
   |                                                                |
   |                                                                |
   +----------------------------------------------------------------+
   |                  |
   |                  |
   |    SCLK times    |
   |                  |
   |                  |
   +------------------+
   |                  |
   |  SCLK directory  |
   |                  |
   +------------------+
   |      NPREC       |
   +------------------+
</PRE>
   The final component, NPREC, gives the total number of pointing instances
   described by the segment.
<P>
 
   Preceding it, starting from the top, are NPREC pointing records, ordered
   with respect to time, each consisting of the four or seven double
   precision numbers described above.
<P>
 
   Following the pointing section are the NPREC encoded spacecraft clock
   times corresponding to the pointing records. These must be in strictly
   increasing order.
<P>
 
   Following the SCLK times is a very simple SCLK directory. The directory
   contains INT( (NPREC-1) / 100 ) entries. The Ith directory entry
   contains the midpoint of the (I*100)th and the (I*100 + 1)st SCLK time.
   Thus,
<P>
 
<PRE>
   Directory(1) = ( SCLKDP(100) + SCLKDP(101) )   / 2
 
   Directory(2) = ( SCLKDP(200) + SCLKDP(201) )   / 2
</PRE>
   and so on.
<P>
 
   If there are 100 or fewer entries, there is no directory. The directory
   is used to narrow down searches for pointing records to groups of 100 or
   less. Midpoints of adjacent times are used so that if an input time
   falls on one side of the directory time, then the group represented by
   that side is guaranteed to contain the time closest to the input time.
<P>
 
<BR><BR>
<A NAME="Type 1 functions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Type 1 functions
</H3><P><BR><BR>
   There are several CK functions that support data type 1. Their names and
   functions are:
<P>
 
<DL><DT>
<B>
 <a href="../cspice/ckw01_c.html">ckw01_c</a>
</B><BR><BR>
<DD>
 writes a type 1 segment to a file.<BR>
</DL>
<DL><DT>
<B>
 ckr01_
</B><BR><BR>
<DD>
 reads a pointing record from a type 1 segment that satisfies a request
for pointing at a given time.<BR>
</DL>
<DL><DT>
<B>
 cke01_
</B><BR><BR>
<DD>
 evaluates the record supplied by CKR01.<BR>
</DL>
<DL><DT>
<B>
 cknr01_
</B><BR><BR>
<DD>
 gives the number of pointing instances in a type 1 segment.<BR>
</DL>
<DL><DT>
<B>
 ckgr01_
</B><BR><BR>
<DD>
 gets the Ith pointing instance from a type 1 segment.<BR>
</DL>
<BR><BR>
<A NAME="Data Type 2"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Data Type 2
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The following method of storing and evaluating continuous pointing data
   for a spacecraft structure defines C-kernel data type 2.
<P>
 
   A type 2 segment consists of disjoint intervals of time during which the
   angular velocity of the spacecraft is constant. Thus, throughout an
   interval, the spacecraft structure rotates from its initial position
   about a fixed right-handed axis defined by the direction of the angular
   velocity vector at a constant rate equal to the magnitude of that
   vector.
<P>
 
   A type 2 CK segment contains the following information for each
   interval:
<P>
 
<UL>
<TT>1.</TT> The encoded spacecraft clock START and STOP times for the interval.
<BR><BR></UL>
<UL>
<TT>2.</TT> The quaternion representing the C-matrix associated with the start time of
the interval.
<BR><BR></UL>
<UL>
<TT>3.</TT> The constant angular velocity vector, in radians per second, for the
interval.
<BR><BR></UL>
<UL>
<TT>4.</TT> A factor which relates seconds and encoded SCLK ticks. This is necessary to
convert the difference between the requested and interval start times from
SCLK to seconds.
<BR><BR></UL>
   The orientation of a spacecraft structure may be determined from the
   above information at any time that is within the bounds of one of the
   intervals.
<P>
 
   Every type 2 segment is organized into four parts.
<P>
 
<PRE>
   +----------------------------------------------------------------+
   |                                                                |
   |                                                                |
   |                          Pointing                              |
   |                                                                |
   |                                                                |
   +----------------------------------------------------------------+
   |                    |
   |                    |
   |  SCLK start times  |
   |                    |
   |                    |
   +--------------------+
   |                    |
   |                    |
   |  SCLK stop times   |
   |                    |
   |                    |
   +--------------------+
   |                    |
   |  SCLK directory    |
   |                    |
   +--------------------+
</PRE>
   The first part of a segment contains pointing records which are ordered
   with respect to their corresponding interval start times. A type 2
   pointing record contains eight double precision numbers in the following
   form:
<P>
 
<PRE>
   +-------+-------+-------+-------+-------+-------+-------+------+
   |       |       |       |       |       |       |       |      |
   |  q0   |  q1   |  q2   |  q3   |  a1   |  a2   |  a3   | rate |
   |       |       |       |       |       |       |       |      |
   +-------+-------+-------+-------+-------+-------+-------+------+
</PRE>
   The first four elements are the components of the quaternion Q =
   (q0,q1,q2,q3) that is used to represent the C-matrix associated with the
   start time of the interval. Next are the three components of the angular
   velocity vector A = (a1,a2,a3) which are given with respect to the base
   reference frame specified in the segment descriptor.
<P>
 
   The last element is a rate which converts the difference between the
   requested and interval start time from encoded SCLK ticks to seconds.
<P>
 
   For segments containing predict data, this factor will be equal to the
   nominal amount of time represented by one tick of the particular
   spacecraft's clock. The nominal rate is given here for several
   spacecraft.
<P>
 
<PRE>
   spacecraft                   seconds / tick ( sec )
   ---------------------        ----------------------
   Galileo                      1 / 120
   Mars Global Surveyor         1 / 256
   Voyager I and II             0.06
</PRE>
   For segments based on real rather than predicted pointing, the rate at
   which the spacecraft clock runs relative to ephemeris time will deviate
   from the nominal rate. The creator of the segment will need to determine
   an average value for this rate over the time period of the interval.
<P>
 
   Located after the pointing data are the interval START times followed by
   the STOP times.
<P>
 
   The START and STOP times should be ordered and in encoded SCLK form. The
   intervals should be disjoint except for possibly at the endpoints. If an
   input request time falls on an overlapping endpoint then the interval
   used will be the one corresponding to the start time. Degenerate
   intervals in which the STOP time equals the START time are not allowed.
<P>
 
   Following the STOP times is a very simple directory of spacecraft clock
   times containing INT( (NPREC-1)/100 ) entries, where NPREC is the number
   of pointing intervals. The Ith directory entry contains the midpoint of
   the (I*100)th STOP and the (I*100 + 1)st START SCLK time.
<P>
 
<PRE>
   Thus,
 
   Directory(1) = ( STOP(100) + START(101) )   / 2
 
   Directory(2) = ( STOP(200) + START(201) )   / 2
 
   .
   .
   .
</PRE>
   If there are 100 or fewer entries then there is no directory. The
   directory is used to narrow down searches for pointing records to groups
   of 100 or less.
<P>
 
<BR><BR>
<A NAME="Type 2 functions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Type 2 functions
</H3><P><BR><BR>
   There are several CK functions that support data type 2. Their names and
   functions are:
<P>
 
<DL><DT>
<B>
 <a href="../cspice/ckw02_c.html">ckw02_c</a>
</B><BR><BR>
<DD>
 writes a type 2 segment to a file.<BR>
</DL>
<DL><DT>
<B>
 ckr02_
</B><BR><BR>
<DD>
 reads a pointing record from a type 2 segment that satisfies a request
for pointing at a given time.<BR>
</DL>
<DL><DT>
<B>
 cke02_
</B><BR><BR>
<DD>
 evaluates the record supplied by CKR02.<BR>
</DL>
<DL><DT>
<B>
 cknr02_
</B><BR><BR>
<DD>
 gives the number of pointing records in a type 2 segment.<BR>
</DL>
<DL><DT>
<B>
 ckgr02_
</B><BR><BR>
<DD>
 gets the Ith pointing record from a type 2 segment.<BR>
</DL>
<BR><BR>
<A NAME="Data Type 3"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Data Type 3
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The following method of storing and evaluating discrete pointing data
   for a spacecraft structure defines C-kernel data type 3.
<P>
 
   A type 3 segment consists of discrete pointing instances that are
   partitioned into groups within which linear interpolation between
   adjacent pointing instances is valid. Since the pointing instances in a
   segment are ordered with respect to time, these groups can be thought of
   as representing intervals of time over which the pointing of a
   spacecraft structure is given continuously. Therefore, in the
   description that follows, these groups of pointing instances will be
   referred to as interpolation intervals.
<P>
 
   All of the pointing instances in the segment must be ordered by encoded
   spacecraft clock time and must belong to one and only one interpolation
   interval. The intervals must begin and end at times for which there are
   pointing instances in the segment. The CK software that evaluates the
   data in the segment does not extrapolate pointing past the bounds of the
   intervals.
<P>
 
   A user's view of the time coverage provided by a type 3 segment can be
   viewed pictorially as follows:
<P>
 
<PRE>
 
   pointing instances:     0-0-0-0-0----0-0-0-0-0-----0------0-0-0-0
                           |       |    |       |     |      |     |
   interval bounds:       BEG      |   BEG      |    BEG    BEG    |
                                  END          END   END          END
 
</PRE>
   In the above picture, the zeros indicate the times associated with the
   discrete pointing instances and the vertical bars show the bounds of the
   interpolation intervals that they are partitioned into. Note that the
   intervals begin and end at times associated with pointing instances.
   Also note that intervals consisting of just a single pointing instance
   are allowed.
<P>
 
   When pointing is desired for a time that is within the bounds of one of
   the intervals, the CK reader functions return interpolated pointing at
   the request time. In the example below, the pointing request time is
   indicated by SCLKDP and the user-supplied tolerance is given by TOL. In
   this example the tolerance argument of the CK readers could be set to
   zero and pointing would still be returned.
<P>
 
<PRE>
                                     SCLKDP    TOL
                                          \   /
                                           | |
                                           |/ \
                                       [---+---]
                                       .   .   .
                                       .   .   .
   pointing instances:     0-0-0-0-0----0-0-0-0-0-----0------0-0-0-0
                           |       |    |  ^    |     |      |     |
   interval bounds:       BEG      |   BEG |    |    BEG    BEG    |
                                  END      |   END   END          END
                                           |
            CK reader returns interpolated pointing at this time.
</PRE>
   When a request time falls in a gap between intervals, no extrapolation
   is performed. Instead, pointing is returned for the interval endpoint
   closest to the request time, provided that time is within the user
   supplied tolerance. In this example if the tolerance were set to zero no
   pointing would be returned.
<P>
 
<PRE>
                                            SCLKDP
                                                 \   TOL
                                                  | /
                                                  |/\
                                              [---+---]
                                              .   .   .
                                              .   .   .
   pointing instances:     0-0-0-0-0----0-0-0-0-0-----0------0-0-0-0
                           |       |    |       |     |      |     |
   interval bounds:       BEG      |   BEG      |    BEG    BEG    |
                                  END          END   END          END
                                                ^
                                                |
                                CK reader returns this instance.
</PRE>
   The physical structure of the data stored in a type 3 segment is as
   follows:
<P>
 
<PRE>
   +-----------------------------------------------------------------+
   |                                                                 |
   |                                                                 |
   |                          Pointing                               |
   |                                                                 |
   |                                                                 |
   +-----------------------------------------------------------------+
   |                        |
   |  SCLK times            |
   |                        |
   +------------------------+
   |                        |
   |  SCLK directory        |
   |                        |
   +------------------------+
   |                        |
   |  Interval start times  |
   |                        |
   +------------------------+
   |                        |
   |  Start times directory |
   |                        |
   +------------------------+
   |                        |
   |  Number of intervals   |
   |                        |
   +------------------------+
   |                        |
   |  Number of pointing    |
   |      instances         |
   |                        |
   +------------------------+
</PRE>
   In the discussion that follows let NPREC be the number of pointing
   instances in the segment and let NUMINT be the number of intervals into
   which the pointing instances are partitioned.
<P>
 
   The first part of a segment contains NPREC pointing records which are
   ordered with respect to increasing time. Depending on whether or not the
   segment contains angular velocity data, a type 3 pointing record
   contains either four or seven double precision numbers in the following
   form:
<P>
 
<PRE>
   +--------+--------+--------+--------+--------+--------+--------+
   |        |        |        |        |        |        |        |
   |   q0   |   q1   |   q2   |   q3   |   a1   |   a2   |   a3   |
   |        |        |        |        |        |        |        |
   +--------+--------+--------+--------+--------+--------+--------+
</PRE>
   The first four elements are the components of the quaternion Q =
   (q0,q1,q2,q3) that is used to represent the pointing of the instrument
   or spacecraft structure to which the segment applies. Next are the three
   components of the angular velocity vector AV = (a1,a2,a3) which are
   given with respect to the base reference frame specified in the segment
   descriptor. These components are optional and are present only if the
   segment contains angular velocity data as specified by the fourth
   integer component of the segment descriptor.
<P>
 
   Following the pointing data are the NPREC times associated with the
   pointing instances. These times are in encoded SCLK form and should be
   strictly increasing.
<P>
 
   Immediately following the last time is a very simple directory of the
   SCLK times. The directory contains INT( (NPREC-1) / 100 ) entries. The
   Ith directory entry contains the (I*100)th SCLK time. Thus,
<P>
 
<PRE>
   Directory(1) = SCLKDP(100)
 
   Directory(2) = SCLKDP(200)
 
   .
   .
   .
</PRE>
   If there are 100 or fewer entries, there is no directory. The directory
   is used to narrow down searches for pointing records to groups of 100 or
   less.
<P>
 
   Next are the NUMINT start times of the intervals that the pointing
   instances are partitioned into. These times are given in encoded
   spacecraft clock and must be strictly increasing. They must also be
   equal to times for which there are pointing instances in the segment.
   Note that the interval stop times are not stored in the segment. They
   are not needed because the stop time of the Ith interval is simply the
   time associated with the pointing instance that precedes the start time
   of the (I+1)th interval.
<P>
 
   Following the interval start times is a directory of these times. This
   directory is constructed in a form similar to the directory for the
   times associated with the pointing instances. The start times directory
   contains INT ( (NUMINT-1) / 100 ) entries and contains every 100th start
   time. Thus:
<P>
 
<PRE>
   Directory(1) = START(100)
 
   Directory(2) = START(200)
 
   .
   .
   .
</PRE>
   Finally, the last two words in the segment give the total number of
   interpolation intervals (NUMINT) and the total number of pointing
   instances (NPREC) in the segment.
<P>
 
   A segment writer function is provided which calls the low level DAF
   functions necessary to write a type 3 segment to a C-kernel. However,
   the creator of the segment is responsible for determining whether or not
   it is valid to interpolate between adjacent pointing instances, and thus
   how they should be partitioned into intervals. See the header of the
   function <a href="../cspice/ckw03_c.html">ckw03_c</a> for a complete description of the inputs required to
   write a segment.
<P>
 
<BR><BR>
<A NAME="Linear Interpolation Algorithm"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Linear Interpolation Algorithm
</H3><P><BR><BR>
   The linear interpolation performed between adjacent pointing instances
   by the CK software is defined by the following algorithm:
<P>
 
<UL>
<TT>1.</TT> Let t be the time for which pointing is desired and let CMAT1 and CMAT2 be
C-matrices associated with times t1 and t2 such that:
<BR><BR></UL>
<PRE>
                           t1 &lt;= t &lt;= t2,  where t1 &lt; t2.
</PRE>
<UL>
<TT>2.</TT> Assume that the spacecraft frame rotates about a fixed axis at a constant
angular rate from time t1 to time t2. Then the rotation axis and angle can
be derived from the rotation matrix ROT12 where:
<BR><BR></UL>
<PRE>
                                T                       T
                           CMAT2   =  ROT12    *   CMAT1
 
               or
                                           T
                           ROT12   =  CMAT2    *   CMAT1
</PRE>
<UL>
<TT>3.</TT> Obtain the axis and angle of the rotation from the matrix ROT12. Let the
axis vector of the rotation be AXIS and the rotation angle be ANGLE.
<BR><BR></UL>
<UL>
<TT>4.</TT> To obtain pointing information at time t, rotate the spacecraft frame about
the vector AXIS from its orientation at time t1 by the angle THETA where:
<BR><BR></UL>
<PRE>
                                                ( t  - t1 )
                           THETA  =  ANGLE  *   -----------
                                                ( t2 - t1 )
</PRE>
<UL>
<TT>5.</TT> Thus if ROT1t is the matrix that rotates vectors by the angle THETA about
the vector AXIS, then the desired C-matrix is given by:
<BR><BR></UL>
<PRE>
 
                               T                     T
                           CMAT  =  ROT1t   *   CMAT1
 
                                                     T
                           CMAT  =  CMAT1   *   ROT1t
</PRE>
<UL>
<TT>6.</TT> The angular velocity is treated independently of the C-matrix. If it is
requested, then the AV at time t is the weighted average of the angular
velocity vectors at time t1 and time t2:
<BR><BR></UL>
<PRE>
 
                              ( t  - t1 )
                        W  =  -----------
                              ( t2 - t1 )
 
 
                        AV  = ( 1 - W ) * AV1   +   W * AV2
 
</PRE>
<BR><BR>
<A NAME="Type 3 functions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Type 3 functions
</H3><P><BR><BR>
   There are several CK functions that support data type 3. Their names and
   function are:
<P>
 
<DL><DT>
<B>
 <a href="../cspice/ckw03_c.html">ckw03_c</a>
</B><BR><BR>
<DD>
 writes a type 3 segment to a file.<BR>
</DL>
<DL><DT>
<B>
 ckr03_
</B><BR><BR>
<DD>
 reads a pointing record from a type 3 segment that satisfies a request
for pointing at a given time.<BR>
</DL>
<DL><DT>
<B>
 cke03_
</B><BR><BR>
<DD>
 evaluates the record supplied by CKR03.<BR>
</DL>
<DL><DT>
<B>
 cknr03_
</B><BR><BR>
<DD>
 gives the number of pointing instances in a type 3 segment.<BR>
</DL>
<DL><DT>
<B>
 ckgr03_
</B><BR><BR>
<DD>
 gets the Ith pointing instance from a type 3 segment.<BR>
</DL>
<BR><BR>
<A NAME="Data Type 4"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Data Type 4
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The following method of storing and evaluating continuous pointing data
   for a spacecraft structure defines C-kernel data Type 4.
<P>
 
   A Type 4 segment contains one or more sets of Chebychev polynomial
   coefficients that approximate orientation and optionally angular rate of
   a spacecraft, spacecraft structure or science instrument. Each set of
   coefficients is valid for a specific interval of time, the bounds of
   which are attached to the set. A typical Type 4 segment coverage is
   shown in the picture below:
<P>
 
<PRE>
    continuous pointing:    0-------0-------0    00     0-----0
                            |       |       |    ||     |     |
    interval bounds:       BEG      |BEG    |  BEG|    BEG    |
                                 END       END    END        END
</PRE>
   In the picture, the zeros indicate the times associated with the bounds
   of intervals where pointing is available (between BEG and END) and not
   available (between END and BEG). Zero length intervals are not allowed.
<P>
 
   When pointing is desired for a time that is within the bounds of one of
   the intervals, the CK reader functions return pointing and optionally
   angular rate computed at the request time from Chebychev polynomials for
   that interval. In the example below, the pointing request time is
   indicated by SCLKDP and the user supplied tolerance is given by TOL. In
   this example the tolerance argument could be set to zero and pointing
   would still be returned.
<P>
 
<PRE>
                                   SCLKDP    TOL
                                        \   /
                                         | |
                                         |/ \
                                     [---+---]
                                     .   .   .
                                     .   .   .
    continuous pointing:    0-------0-------0    00     0-----0
                            |       |    ^  |    ||     |     |
    interval bounds:       BEG      |BEG .  |  BEG|    BEG    |
                                 END     . END    END        END
                                         .
                       CK reader returns pointing at this time.
</PRE>
   When a request time falls in a gap between intervals, pointing is
   evaluated for the interval endpoint closest to the request time if there
   is an endpoint within the user supplied tolerance of the request time.
   In this example if the tolerance were set to zero no pointing would be
   returned.
<P>
 
<PRE>
                                        SCLKDP    TOL
                                             \   /
                                              | |
                                              |/ \
                                          [---+---]
                                          .   .   .
                                          .   .   .
    continuous pointing:    0-------0-------0    00     0-----0
                            |       |       |    ||     |     |
    interval bounds:       BEG      |BEG    |  BEG|    BEG    |
                                 END       END    END        END
                                            ^
                                            |
                                CK reader returns this instance.
</PRE>
   The CK data Type 4 uses the CSPICE concept of a generic segment to store
   a collection of packets each of which models the pointing of a
   spacecraft, spacecraft structure or science instrument during some
   interval of time. Each packet contains sets of coefficients for
   Chebychev polynomials that approximate the orientation quaternion. The
   packets may optionally contain polynomial coefficients for angular
   velocity vector components. The time intervals covered by individual
   packets in a CK Type 4 segment are non-overlapping and can have variable
   length. There can be gaps between intervals; the gaps can also be of
   variable length.
<P>
 
   The storage, arrangement and retrieval of packets is handled by the
   CSPICE generic segment functions. That software is described in the
   document GENSEG.REQ. We only review the pertinent points about generic
   segments here.
<P>
 
   A generic CK segment contains several logical data partitions:
<P>
 
<UL>
<TT>1.</TT> A partition for constant values to be associated with each data packet in
the segment.
<BR><BR></UL>
<UL>
<TT>2.</TT> A partition for the data packets.
<BR><BR></UL>
<UL>
<TT>3.</TT> A partition for packet coverage begin times.
<BR><BR></UL>
<UL>
<TT>4.</TT> A partition for a packet directory, if the segment contains variable sized
packets.
<BR><BR></UL>
<UL>
<TT>5.</TT> A partition for a packet coverage begin time directory.
<BR><BR></UL>
<UL>
<TT>6.</TT> A reserved partition that is not currently used. This partition is only for
the use of the NAIF group at the Jet Propulsion Laboratory (JPL).
<BR><BR></UL>
<UL>
<TT>7.</TT> A partition for the metadata which describes the locations and sizes of
other partitions as well as providing some additional descriptive
information about the generic segment.
<BR><BR></UL>
<PRE>
                  +============================+
                  |         Constants          |
                  +============================+
                  |          Packet 1          |
                  |----------------------------|
                  |          Packet 2          |
                  |----------------------------|
                  |              .             |
                  |              .             |
                  |              .             |
                  |----------------------------|
                  |          Packet N          |
                  +============================+
                  |      Reference Times       |
                  +============================+
                  |      Packet Directory      |
                  +============================+
                  |       Time  Directory      |
                  +============================+
                  |       Reserved  Area       |
                  +============================+
                  |      Segment Metadata      |
                  +----------------------------+
</PRE>
   Only the placement of the metadata at the end of a generic segment is
   required. The other data partitions may occur in any order in the
   generic segment because the metadata will contain pointers to their
   appropriate locations within the generic segment.
<P>
 
   In the case of Type 4 CK segments each ``packet'' contains time of the
   middle of approximation interval SCLKDP, radius of approximation
   interval RADIUS, numbers of coefficients for each quaternion and angular
   rate component encoded in a single DP number, and four or seven sets of
   Chebychev polynomial coefficients which approximate four quaternion
   components and (optionally) three angular velocity components during the
   given time interval.
<P>
 
   In order to provide a more compact data representation the number of
   coefficients can vary from component to component. To accomodate this
   generic segments with variable sized data packets are used as the
   underlying structure holding CK Type 4 data.
<P>
 
   Each data packet has the following structure:
<P>
 
<PRE>
         +----------------------------------------------+
         |        Midpoint of approx. interval          |
         +----------------------------------------------+
         |            Radius of interval                |
         +----------------------------------------------+
         |          Number of coefficients for          |
         |          (Q0,Q1,Q2,Q3,AV1,AV2,AV3)           |
         +----------------------------------------------+
         |           q0 Cheby coefficients              |
         +----------------------------------------------+
         |           q1 Cheby coefficients              |
         +----------------------------------------------+
         |           q2 Cheby coefficients              |
         +----------------------------------------------+
         |           q3 Cheby coefficients              |
         +----------------------------------------------+
         |      av1 Cheby coefficients (optional)       |
         +----------------------------------------------+
         |      av2 Cheby coefficients (optional)       |
         +----------------------------------------------+
         |      av3 Cheby coefficients (optional)       |
         +----------------------------------------------+
</PRE>
   The maximum Chebychev polynomial degree allowed in CK Type 4 is 18.
<P>
 
   Packets within a CK Type 4 segment must be stored in strictly time
   increasing order.
<P>
 
   The numbers of coefficients for each quaternion and angular rate
   component are packed into a single DP number using an encoding function
   which is a part of the CSPICE CK4 functions family. This DP number
   occurs as the third entry in a packet.
<P>
 
   The ``constants'' partition in CK Type 4 does not contain any values.
<P>
 
   The reference times partition contains an ordered collection of encoded
   spacecraft clock times. The i'th reference time corresponds to the
   beginning of the interval for which the i'th packet can be used to
   determine the pointing of spacecraft.
<P>
 
   The ``time directory'' contains every 100th reference time. The time
   directory is used to efficiently locate the reference times that should
   be associated with a time for which a pointing has been requested.
<P>
 
   As noted above the exact location of the various partitions must be
   obtained from the metadata contained at the end of the segment.
<P>
 
   Access to the Type 4 CK data is made via the CSPICE generic segment
   functions.
<P>
 
   Type 4 CK segments should be created using CK Type 4 writer functions
   ckw04b_, ckw04a_ and ckw04e_, provided in the CSPICE.
<P>
 
<BR><BR>
<A NAME="CK Type 4 pointing evaluation algorithm"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> CK Type 4 pointing evaluation algorithm
</H3><P><BR><BR>
   The CSPICE function chbval_ is used to evaluate individual quaternion
   and angular rate components from the corresponding Chebychev polynomial
   coefficients. Refer to the header of the chbval_ function for more
   information.
<P>
 
<BR><BR>
<A NAME="Type 4 functions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Type 4 functions
</H3><P><BR><BR>
   There are several CK functions that support data Type 4. Their names and
   functions are:
<P>
 
<DL><DT>
<B>
 ckr04_
</B><BR><BR>
<DD>
 reads a record from a Type 4 segment that satisfies a request for
pointing at a given time.<BR>
</DL>
<DL><DT>
<B>
 cke04_
</B><BR><BR>
<DD>
 evaluates the record supplied by ckr04_.<BR>
</DL>
<DL><DT>
<B>
 cknr04_
</B><BR><BR>
<DD>
 gives the total number of data packets in a Type 4 segment.<BR>
</DL>
<DL><DT>
<B>
 ckgr04_
</B><BR><BR>
<DD>
 gets the I'th record from a Type 4 segment.<BR>
</DL>
<DL><DT>
<B>
 ckw04b_
</B><BR><BR>
<DD>
 begins a Type 4 CK data segment<BR>
</DL>
<DL><DT>
<B>
 ckw04a_
</B><BR><BR>
<DD>
 adds data to a Type 4 CK segment<BR>
</DL>
<DL><DT>
<B>
 ckw04e_
</B><BR><BR>
<DD>
 ends a Type 4 CK data segment<BR>
</DL>
<BR><BR>
<A NAME="Data Type 5"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Data Type 5
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   CK type 5 has been provided to support accurate duplication within the
   CK system of spacecraft attitude data used by the European Space Agency
   (ESA) on the Mars Express (MEX) and Rosetta missions. However, the
   algorithms used by CK type 5 are very general; type 5's applicability is
   by no means limited to these missions.
<P>
 
   Because of the possibility of evolution of the mathematical
   representations of spacecraft attitude used by ESA, CK type 5 is
   designed to accommodate multiple representations, thereby avoiding a
   proliferation of CK data types. CK type 5 refers to each supported
   mathematical representation of attitude data as a ``subtype.''
<P>
 
   Currently CK type 5 supports four subtypes. All of these use polynomial
   interpolation to provide continuous pointing data. However, the creator
   of a type 5 segment may wish to restrict the intervals over which
   interpolation is allowed to occur. To support this capability, CK type 5
   uses the same interpolation interval scheme as does type 3. This scheme
   will be explained shortly.
<P>
 
   The CK type 5 subtypes are as follows:
<P>
 
<UL>
<TT>1.</TT> Subtype 0:
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> Sliding-window Hermite interpolation of quaternions and quaternion
derivatives. Attitude and angular velocity are represented by a series of
8-element ``packets'' and associated time tags. The time tags may be
unequally spaced. Each packet contains four quaternion components followed
by four quaternion time derivative components. A quaternion representing
attitude at a request time is derived by using Hermite interpolation on
each quaternion component and the corresponding derivative, where the
values to be interpolated are obtained for a consecutive series of epochs
centered at the request time. The interpolated quaternion is then unitized.
The same interpolation degree is used for each quaternion component.
<BR><BR></UL>
<UL>
<TT>2.</TT> Subtype 1:
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> Sliding-window Lagrange interpolation of quaternions. Attitude is
represented by a series of 4-element ``packets'' and associated time tags.
The time tags may be unequally spaced. Each packet contains four quaternion
components. A quaternion representing attitude at a request time is derived
by using Lagrange interpolation on each quaternion component, where the
values to be interpolated are obtained for a consecutive series of epochs
centered at the request time. The interpolated quaternion is then unitized.
The same interpolation degree is used for each quaternion component.
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> Angular velocity is obtained by first forming the time derivative of the
quaternion using the derivatives of the interpolating polynomials, then
combining the quaternion and its derivative to obtain angular velocity.
<BR><BR></UL>
<UL>
<TT>3.</TT> Subtype 2:
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> Sliding-window Hermite interpolation of quaternions and angular velocity.
Attitude and angular velocity are represented by a series of 14-element
``packets'' and associated time tags. The time tags may be unequally
spaced. Each packet contains four quaternion components, four quaternion
derivative components, three angular velocity components, and three angular
acceleration components. A quaternion representing attitude at a request
time is derived by using Hermite interpolation on each quaternion component
and the corresponding derivative, where the values to be interpolated are
obtained for a consecutive series of epochs centered at the request time.
The interpolated quaternion is then unitized. Angular velocity is obtained
by using Hermite interpolation on each angular velocity component and the
corresponding derivative. The attitude and angular velocity resulting from
this interpolation method are in principle independent. The same
interpolation degree is used for each quaternion and angular velocity
component.
<BR><BR></UL>
<UL>
<TT>4.</TT> Subtype 3:
<BR><BR></UL>
<UL>
<TT>&#32;&#32;</TT> Sliding-window Lagrange interpolation of quaternions and angular velocity.
Attitude and angular velocity are represented by a series of 7-element
``packets'' and associated time tags. The time tags may be unequally
spaced. Each packet contains four quaternion components and three angular
velocity components. A quaternion representing attitude at a request time
is derived by using Lagrange interpolation on each quaternion component,
where the values to be interpolated are obtained for a consecutive series
of epochs centered at the request time. The interpolated quaternion is then
unitized. Angular velocity is obtained by using Lagrange interpolation on
each angular velocity component. The attitude and angular velocity
resulting from this interpolation method are in principle independent. The
same interpolation degree is used for each quaternion and angular velocity
component.
<BR><BR></UL>
   The sliding-window interpolation technique used by this data type works
   as follows: for any request epoch, the data type defines a component of
   a quaternion or angular velocity by interpolating a set of values of
   that component defined on a set of consecutive time tags---a
   "window"---centered as closely as possible to the request epoch. The
   nominal window size is dictated by the degree and type (Hermite vs
   Lagrange) of the interpolating polynomials. Normally the window of time
   tags has even size, and the window is selected so that the request time
   is located between the two central time tags in the window.
<P>
 
   When the request time is near a segment or interpolation interval
   boundary, the window is truncated if necessary on the side closest to
   the boundary. If a segment or interpolation interval contains too few
   packets to form a window of nominal size, a window will be constructed
   from the all of the available packets that lie within the nominal window
   location. In this case the window size may be odd. In any case the
   window never includes more than WNDSIZ/2 time tags on either side of the
   request time, where WNDSIZ is the nominal window size.
<P>
 
   Regarding interpolation intervals: the pointing time tags in a type 5
   segment are partitioned into groups within which polynomial
   interpolation between adjacent groups of WNDSIZ pointing instances is
   valid. Since the pointing instances in a segment are ordered with
   respect to time, these groups can be thought of as representing
   intervals of time over which the pointing of the spacecraft (or a
   spacecraft instrument or structure) is given continuously. Therefore, in
   the description that follows, these groups of pointing instances will be
   referred to as interpolation intervals.
<P>
 
   All of the pointing instances in the segment must be ordered by encoded
   spacecraft clock time and must belong to one and only one interpolation
   interval. The intervals must begin and end at times for which there are
   pointing instances in the segment. The CK software that evaluates the
   data in the segment does not extrapolate pointing past the bounds of the
   intervals.
<P>
 
   A user's view of the time coverage provided by a type 5 segment can be
   viewed pictorially as follows:
<P>
 
<PRE>
 
   pointing instances:     0-0-0-0-0----0-0-0-0-0-----0------0-0-0-0
                           |       |    |       |     |      |     |
   interval bounds:       BEG      |   BEG      |    BEG    BEG    |
                                  END          END   END          END
 
</PRE>
   In the above picture, the zeros indicate the times associated with the
   discrete pointing instances and the vertical bars show the bounds of the
   interpolation intervals that they are partitioned into. Note that the
   intervals begin and end at times associated with pointing instances.
   Also note that intervals consisting of just a single pointing instance
   are allowed.
<P>
 
   When pointing is desired for a time that is within the bounds of one of
   the intervals, the CK reader functions return interpolated pointing at
   the request time. In the example below, the pointing request time is
   indicated by SCLKDP and the user supplied tolerance is given by TOL. In
   this example the tolerance argument of the CK readers could be set to
   zero and pointing would still be returned.
<P>
 
<PRE>
                                     SCLKDP    TOL
                                          \   /
                                           | |
                                           |/ \
                                       [---+---]
                                       .   .   .
                                       .   .   .
   pointing instances:     0-0-0-0-0----0-0-0-0-0-----0------0-0-0-0
                           |       |    |  ^    |     |      |     |
   interval bounds:       BEG      |   BEG |    |    BEG    BEG    |
                                  END      |   END   END          END
                                           |
            CK reader returns interpolated pointing at this time.
</PRE>
   When a request time falls in a gap between intervals, no extrapolation
   is performed. Instead, pointing is returned for the interval endpoint
   closest to the request time, provided that time is within the user
   supplied tolerance. In this example if the tolerance were set to zero no
   pointing would be returned.
<P>
 
<PRE>
                                            SCLKDP
                                                 \   TOL
                                                  | /
                                                  |/\
                                              [---+---]
                                              .   .   .
                                              .   .   .
   pointing instances:     0-0-0-0-0----0-0-0-0-0-----0------0-0-0-0
                           |       |    |       |     |      |     |
   interval bounds:       BEG      |   BEG      |    BEG    BEG    |
                                  END          END   END          END
                                                ^
                                                |
                                CK reader returns this instance.
</PRE>
   The physical structure of the data stored in a type 5 segment is as
   follows:
<P>
 
<PRE>
   +-----------------------+
   | Packet 1              |
   +-----------------------+
   | Packet 2              |
   +-----------------------+
               .
               .
               .
   +-----------------------+
   | Packet N              |
   +-----------------------+
   | Epoch 1               |
   +-----------------------+
   | Epoch 2               |
   +-----------------------+
               .
               .
               .
   +----------------------------+
   | Epoch N                    |
   +----------------------------+
   | Epoch 100                  | (First directory)
   +----------------------------+
               .
               .
               .
   +----------------------------+
   | Epoch ((N-1)/100)*100      | (Last directory)
   +----------------------------+
   | Start time 1               |
   +----------------------------+
   | Start time 2               |
   +----------------------------+
               .
               .
               .
   +----------------------------+
   | Start time NUMINT          |
   +----------------------------+
   | Start time 100             | (First interval start
   +----------------------------+  time directory)
               .
               .
               .
   +----------------------------+
   | Start ((NUMINT-1)/100)*100 | (Last interval start
   +----------------------------+  time directory)
   | Seconds per tick           |
   +----------------------------+
   | Subtype code               |
   +----------------------------+
   | Window size                |
   +----------------------------+
   | Number of interp intervals |
   +----------------------------+
   | Number of packets          |
   +----------------------------+
</PRE>
   In the discussion that follows let N be the number of pointing instances
   in the segment and let NUMINT be the number of intervals into which the
   pointing instances are partitioned.
<P>
 
   The first part of a segment contains N packets (pointing records) which
   are ordered with respect to increasing time. Depending the segment
   subtype, a type 5 packet contains from four to fourteen d.p. numbers.
<P>
 
   Following the pointing data are the N times associated with the pointing
   instances. These times are in encoded SCLK form and should be strictly
   increasing.
<P>
 
   Immediately following the last time is a very simple directory of the
   SCLK times. The directory contains INT( (N-1) / 100 ) entries. The Ith
   directory entry contains the (I*100)th SCLK time. Thus,
<P>
 
<PRE>
   Directory(1) = SCLKDP(100)
 
   Directory(2) = SCLKDP(200)
 
   .
   .
   .
</PRE>
   If there are 100 or fewer entries, there is no directory. The directory
   is used to narrow down searches for pointing records to groups of 100 or
   less.
<P>
 
   Next are the NUMINT start times of the intervals that the pointing
   instances are partitioned into. These times are given in encoded
   spacecraft clock and must be strictly increasing. They must also be
   equal to times for which there are pointing instances in the segment.
   Note that the interval stop times are not stored in the segment. They
   are not needed because the stop time of the Ith interval is simply the
   time associated with the pointing instance that precedes the start time
   of the (I+1)th interval.
<P>
 
   Following the interval start times is a directory of these times. This
   directory is constructed in a form similar to the directory for the
   times associated with the pointing instances. The start times directory
   contains INT ( (NUMINT-1) / 100 ) entries and contains every 100th start
   time. Thus:
<P>
 
<PRE>
   Directory(1) = START(100)
 
   Directory(2) = START(200)
 
   .
   .
   .
</PRE>
   Finally, the last five words in the segment are:
<P>
 
<UL>
<TT>--</TT> The nominal rate for the spacecraft clock associated with this kernel,
given in seconds/tick.
<BR><BR></UL>
<UL>
<TT>--</TT> The CK type 5 subtype code.
<BR><BR></UL>
<UL>
<TT>--</TT> The interpolation window size
<BR><BR></UL>
<UL>
<TT>--</TT> the total number of interpolation intervals (NUMINT)
<BR><BR></UL>
<UL>
<TT>--</TT> The total number of packets (pointing instances) (N) in the segment.
<BR><BR></UL>
   A segment writer function is provided which calls the low level DAF
   functions necessary to write a type 5 segment to a C-kernel. However,
   the creator of the segment is responsible for determining whether or not
   it is valid to interpolate between contiguous ranges of pointing
   instances, and thus how they should be partitioned into intervals. See
   the header of the function <a href="../cspice/ckw05_c.html">ckw05_c</a> for a complete description of the
   inputs required to write a segment.
<P>
 
<BR><BR>
<A NAME="Type 5 functions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Type 5 functions
</H3><P><BR><BR>
   There are several CK functions that support data type 5. Their names and
   functions are:
<P>
 
<DL><DT>
<B>
 <a href="../cspice/ckw05_c.html">ckw05_c</a>
</B><BR><BR>
<DD>
 writes a type 5 segment to a file.<BR>
</DL>
<DL><DT>
<B>
 ckr05_
</B><BR><BR>
<DD>
 reads a pointing record from a type 5 segment that satisfies a request
for pointing at a given time.<BR>
</DL>
<DL><DT>
<B>
 cke05_
</B><BR><BR>
<DD>
 evaluates the record supplied by CKR05.<BR>
</DL>
<DL><DT>
<B>
 cknr05_
</B><BR><BR>
<DD>
 gives the number of pointing instances in a type 5 segment.<BR>
</DL>
<DL><DT>
<B>
 ckgr05_
</B><BR><BR>
<DD>
 gets the Ith pointing instance from a type 5 segment.<BR>
</DL>
<BR><BR>
<A NAME="Appendix A --- Summary of C-kernel Functions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Appendix A --- Summary of C-kernel Functions
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
<BR><BR>
<A NAME="Summary of Mnemonics"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Summary of Mnemonics
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   Each C-kernel function name consists of a mnemonic which translates into
   a short description of the function's purpose. Those beginning with
   ```ck''' are names of functions that deal solely with C-kernel files.
   The other functions provide support that is not necessarily C-kernel
   specific.
<P>
 
<PRE>
      Kernel Loading/Unloading Routines
 
   <a href="../cspice/furnsh_c.html">furnsh_c</a>       ( Load kernel file of any type                     )
   <a href="../cspice/unload_c.html">unload_c</a>       ( Unload kernel file of any type                   )
 
 
      C-kernel Routines
 
 
         Wrappers
 
   <a href="../cspice/ckcls_c.html">ckcls_c</a>        ( C-kernel, close a pointing file                  )
   <a href="../cspice/ckcov_c.html">ckcov_c</a>        ( C-kernel, coverage for an instrument             )
   <a href="../cspice/ckgp_c.html">ckgp_c</a>         ( C-kernel, get pointing                           )
   <a href="../cspice/ckgpav_c.html">ckgpav_c</a>       ( C-kernel, get pointing and angular velocity      )
   <a href="../cspice/cklpf_c.html">cklpf_c</a>        ( C-kernel, load pointing file                     )
   <a href="../cspice/ckobj_c.html">ckobj_c</a>        ( C-kernel, instruments in a file                  )
   <a href="../cspice/ckopn_c.html">ckopn_c</a>        ( C-kernel, open a new pointing file               )
   <a href="../cspice/ckupf_c.html">ckupf_c</a>        ( C-kernel, unload pointing file                   )
   <a href="../cspice/ckw01_c.html">ckw01_c</a>        ( C-kernel, write segment to C-kernel, data type 1 )
   <a href="../cspice/ckw02_c.html">ckw02_c</a>        ( C-kernel, write segment to C-kernel, data type 2 )
   <a href="../cspice/ckw03_c.html">ckw03_c</a>        ( C-kernel, write segment to C-kernel, data type 3 )
   <a href="../cspice/ckw05_c.html">ckw05_c</a>        ( C-kernel, write segment to C-kernel, data type 5 )
 
         Lower-level functions
 
   ckbss_         ( C-kernel, begin search for segment               )
   cke01_         ( C-kernel, evaluate pointing record, data type 1  )
   cke02_         ( C-kernel, evaluate pointing record, data type 2  )
   cke03_         ( C-kernel, evaluate pointing record, data type 3  )
   cke04_         ( C-kernel, evaluate pointing record, data type 4  )
   cke05_         ( C-kernel, evaluate pointing record, data type 5  )
   ckgr01_        ( C-kernel, get record, data type 1                )
   ckgr02_        ( C-kernel, get record, data type 2                )
   ckgr03_        ( C-kernel, get record, data type 3                )
   ckgr04_        ( C-kernel, get record, data type 4                )
   ckgr05_        ( C-kernel, get record, data type 5                )
   cknr01_        ( C-kernel, number of records, data type 1         )
   cknr02_        ( C-kernel, number of records, data type 2         )
   cknr03_        ( C-kernel, number of records, data type 3         )
   cknr04_        ( C-kernel, number of records, data type 4         )
   cknr05_        ( C-kernel, number of records, data type 5         )
   ckpfs_         ( C-kernel, pointing from segment                  )
   ckr01_         ( C-kernel, read pointing record, data type 1      )
   ckr02_         ( C-kernel, read pointing record, data type 2      )
   ckr03_         ( C-kernel, read pointing record, data type 3      )
   ckr04_         ( C-kernel, read pointing record, data type 4      )
   ckr04_         ( C-kernel, read pointing record, data type 5      )
   cksns_         ( C-kernel, select next segment                    )
   ckw04a_        ( C-kernel, add to a Type 4 segment                )
   ckw04b_        ( C-kernel, begin a Type 4 segment                 )
   ckw04e_        ( C-kernel, end a Type 4 segment                   )
 
 
      SCLK conversion functions
 
   <a href="../cspice/scdecd_c.html">scdecd_c</a>       ( Decode spacecraft clock                )
   <a href="../cspice/scencd_c.html">scencd_c</a>       ( Encode spacecraft clock                )
   <a href="../cspice/scpart_c.html">scpart_c</a>       ( Spacecraft clock partitions            )
   <a href="../cspice/scfmt_c.html">scfmt_c</a>        ( Spacecraft clock format                )
   <a href="../cspice/sctiks_c.html">sctiks_c</a>       ( Spacecraft clock ticks                 )
   <a href="../cspice/sct2e_c.html">sct2e_c</a>        ( Convert encoded SCLK Ticks to ET       )
   <a href="../cspice/scs2e_c.html">scs2e_c</a>        ( Convert SCLK String to ET              )
   <a href="../cspice/sce2c_c.html">sce2c_c</a>        ( Convert ET to continuous SCLK Ticks    )
   <a href="../cspice/sce2t_c.html">sce2t_c</a>        ( Convert ET to encoded SCLK Ticks       )
   <a href="../cspice/sce2s_c.html">sce2s_c</a>        ( Convert ET to SCLK String              )
 
   <a href="../cspice/utc2et_c.html">utc2et_c</a>       ( UTC to Ephemeris Time                  )
   <a href="../cspice/et2utc_c.html">et2utc_c</a>       ( Ephemeris Time to UTC                  )
 
 
      Inertial Reference frame functions
 
   irfrot_        ( Inertial reference frame, rotate      )
   irfnum_        ( Inertial reference frame number       )
   irfnam_        ( Inertial reference frame name         )
   irfdef_        ( Inertial reference frame, default     )
</PRE>
<BR><BR>
<A NAME="Summary of Calling Sequences"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Summary of Calling Sequences
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
<PRE>
          Kernel Loading/Unloading Routines
 
   <a href="../cspice/furnsh_c.html">furnsh_c</a> ( fname                                                  )
   <a href="../cspice/unload_c.html">unload_c</a> ( fname                                                  )
 
          C-kernel Routines
 
            Wrappers
 
   <a href="../cspice/ckcls_c.html">ckcls_c</a>  ( handle                                                 )
   <a href="../cspice/ckcov_c.html">ckcov_c</a>  ( fname,  idcode, needav, level,  tol,  timsys,  cover   )
   <a href="../cspice/ckgp_c.html">ckgp_c</a>   ( inst,   sclkdp, tol,    ref,    cmat, &amp;clkout, &amp;found  )
   <a href="../cspice/ckgpav_c.html">ckgpav_c</a> ( inst,   sclkdp, tol,    ref,    cmat,   av,    &amp;clkout,
              &amp;found                                                 )
   <a href="../cspice/cklpf_c.html">cklpf_c</a>  ( fname, &amp;handle                                         )
   <a href="../cspice/ckobj_c.html">ckobj_c</a>  ( fname,  ids                                            )
   <a href="../cspice/ckopn_c.html">ckopn_c</a>  ( fname,  ifname, ncomch, &amp;handle                        )
   <a href="../cspice/ckupf_c.html">ckupf_c</a>  (         handle                                         )
   <a href="../cspice/ckw01_c.html">ckw01_c</a>  ( handle, begtim, endtim, inst,   ref,  avflag, segid,
              nprec,  sclkdp, quats,  avvs                           )
   <a href="../cspice/ckw02_c.html">ckw02_c</a>  ( handle, begtim, endtim, inst,   ref,   segid,  nprec,
              start,  stop,   quats,  avvs,   rates                  )
   <a href="../cspice/ckw03_c.html">ckw03_c</a>  ( handle, begtim, endtim, inst,   ref,   avflag, segid,
              nprec,  sclkdp, quats,  avvs,   nints, starts          )
   <a href="../cspice/ckw05_c.html">ckw05_c</a>  ( handle, subtyp, degree, begtim, endtim, inst,   ref,
              avflag, segid,  nprec,  sclkdp, packts, nints,  starts )
 
 
            Lower-level functions
 
   ckbss_  ( inst,    sclkdp, tol,    needav                       )
   cksns_  ( handle,  descr,  segid,  &amp;found, SIDLEN               )
   ckpfs_  ( handle,  descr,  sclkdp, tol,    needav, cmat, av,
             &amp;clkout, &amp;found                                       )
   ckr01_  ( handle,  descr,  sclkdp, tol,    needav, record,
             &amp;found                                                )
   cke01_  ( needav,  record, cmat,   av,     &amp;clkout              )
   cknr01_ ( handle,  descr,  &amp;nprec                               )
   ckgr01_ ( handle,  descr,  recno,  record                       )
   ckr02_  ( handle,  descr,  sclkdp, tol,    record, &amp;found       )
   cke02_  ( needav,  record, cmat,   av,     &amp;clkout              )
   cknr02_ ( handle,  descr,  &amp;nprec                               )
   ckgr02_ ( handle,  descr,  recno,  record                       )
   ckr03_  ( handle,  descr,  sclkdp, tol,    needav, record,
             &amp;found                                                )
   cke03_  ( needav,  record, cmat,   av,     &amp;clkout              )
   cknr03_ ( handle,  descr,  &amp;nprec                               )
   ckgr03_ ( handle,  descr,  recno,  record                       )
   cke04_  ( needav,  record, cmat,   av,     &amp;clkout              )
   ckgr04_ ( handle,  descr,  recno,  record                       )
   cknr04_ ( handle,  descr,  &amp;nrec                                )
   ckr04_  ( handle,  descr,  sclkdp, tol,    needav, record,
             &amp;found                                                )
   ckw04a_ ( handle,  npkts,  pktsiz, pktdat, sclkdp               )
   ckw04b_ ( handle,  begtim, inst,   ref,    avflag, segid,
             REFLEN,  SIDLEN                                       )
   ckw04e_ ( handle,  endtim                                       )
   ckr05_  ( handle,  descr,  sclkdp, tol,    needav, record,
             &amp;found                                                )
   cke05_  ( needav,  record, cmat,   av,     &amp;clkout              )
   cknr05_ ( handle,  descr,  &amp;nprec                               )
   ckgr05_ ( handle,  descr,  recno,  record                       )
 
          SCLK conversion functions
 
   <a href="../cspice/scdecd_c.html">scdecd_c</a> ( sc,     sclkdp, lenout, sclkch         )
   <a href="../cspice/scencd_c.html">scencd_c</a> ( sc,     sclkch, &amp;sclkdp                )
   <a href="../cspice/scpart_c.html">scpart_c</a> ( sc,     nparts, pstart, pstop          )
   <a href="../cspice/scfmt_c.html">scfmt_c</a>  ( sc,     ticks,  lenout, clkstr         )
   <a href="../cspice/sctiks_c.html">sctiks_c</a> ( sc,     clkstr, &amp;ticks                 )
   <a href="../cspice/sct2e_c.html">sct2e_c</a>  ( sc,     sclkdp, &amp;et                    )
   <a href="../cspice/scs2e_c.html">scs2e_c</a>  ( sc,     sclkch, &amp;et                    )
   <a href="../cspice/sce2c_c.html">sce2c_c</a>  ( sc,     et,     &amp;sclkdp                )
   <a href="../cspice/sce2t_c.html">sce2t_c</a>  ( sc,     et,     &amp;sclkdp                )
   <a href="../cspice/sce2s_c.html">sce2s_c</a>  ( sc,     et,     lenout, sclkch         )
 
   <a href="../cspice/utc2et_c.html">utc2et_c</a> ( utcstr, &amp;et                            )
   <a href="../cspice/et2utc_c.html">et2utc_c</a> ( et,     format, prec,  lenout, utcstr  )
 
 
          Inertial Reference frame functions
 
   irfrot_ ( refa,   refb,   rotab  )
   irfnum_ ( name,   &amp;index         )
   irfnam_ ( index,  name,   namlen )
   irfdef_ ( index                  )
</PRE>
<BR><BR>
<A NAME="Appendix B --- Example Program PLANET_POINT"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Appendix B --- Example Program PLANET_POINT
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   The following program shows how C-kernel functions fit together with
   other CSPICE routines to solve a typical problem requiring pointing
   data.
<P>
 
   All of the functions used here are part of CSPICE or the ANSI C library.
<P>
 
<PRE>
   /*
   PROGRAM PLANET_POINT
 
 
      Compute the planetocentric latitude, longitude and radius of
      the point at which the optic axis of an instrument intersects
      the surface of a target planet. Assume that the axis of the
      instrument is along the Z-axis of the instrument fixed
      reference frame.
 
      The following files are required:
 
         1) Kernel file containing planetary constants.
         2) Kernel file containing spacecraft clock (SCLK) data.
         3) SPK file containing planetary and spacecraft
            ephemeris data.
         4) CK file containing instrument pointing data.
 
      The following quantities are required:
 
         1) NAIF integer spacecraft ID
         2) NAIF integer planet ID
         3) NAIF integer instrument ID
         4) SCLK time string
         5) SCLK tolerance.
 
      The following steps are taken to locate the desired point:
 
         1) The inertial pointing (VPNT) of the instrument at
            the input SCLK time is read from the CK file.
 
         2) The apparent position (VTARG) is computed for the
            center of the target body as seen from the spacecraft,
            at the ephemeris time (ET) corresponding to SCLK.
 
            The one-way light time (TAU) from the target to the
            spacecraft is also computed.
 
         3) The transformation (TIBF) from inertial to body-fixed
            coordinates is computed for the epoch ET-TAU, using
            quantities from the planetary constants kernel.
 
         4) The radii (R) of the tri-axial ellipsoid used to model
            the target body are extracted from the planetary
            constants kernel.
 
         5) The position of the observer, in body-fixed coordinates
            is computed using VTARG and TIBF.
 
         6) VPNT is converted to body-fixed coordinates using TIBF.
 
         7) The routine SURFPT computes the point of intersection,
            given the two body-fixed positions, and tri-axial
            ellipsoid radii.
 
   -Particulars
 
       1) The instrument boresight is assumed to define the z-axis
          of the instrument-fixed reference frame. This is reflected
          in the choice of ( 0, 0, 1 ) as the boresight pointing
          vector (VPNT) in instrument-fixed coordinates.
 
   */
 
   #include &lt;stdio.h&gt;
   #include &lt;string.h&gt;
   #include "SpiceUsr.h"
 
 
 
   int main()
   {
 
      /*
      Constants
 
      The inertial reference frame for all output.
      */
      #define   REF            "J2000"
 
      /*
      File name length.
      */
      #define   FILSIZ         256
 
      /*
      Body name length.
      */
      #define   BDNMLN         37
 
      /*
      SCLK string length.
      */
      #define   TIMLEN         35
 
      /*
      Instrument name length.
      */
      #define   INNMLN         32
      /*
      Local variables
      */
      SpiceBoolean            found;
 
      SpiceChar               file      [ FILSIZ ];
      SpiceChar               instch    [ INNMLN ];
      SpiceChar               sclkch    [ TIMLEN ];
      SpiceChar               scname    [ BDNMLN ];
      SpiceChar               targname  [ BDNMLN ];
      SpiceChar               tolch     [ TIMLEN ];
 
      SpiceInt                inst;
      SpiceInt                n;
      SpiceInt                sc;
      SpiceInt                targ;
 
      SpiceDouble             clkout;
      SpiceDouble             cmat   [3][3];
      SpiceDouble             et;
      SpiceDouble             lat;
      SpiceDouble             lon;
      SpiceDouble             r      [3];
      SpiceDouble             radius;
      SpiceDouble             sclkdp;
      SpiceDouble             tau;
      SpiceDouble             tibf   [3][3];
      SpiceDouble             tol;
      SpiceDouble             vpnt   [3];
      SpiceDouble             vpos   [3];
      SpiceDouble             vsurf  [3];
      SpiceDouble             vtarg  [6];
 
 
      /*
      Get all of the files and load them.
      */
      <a href="../cspice/prompt_c.html">prompt_c</a> ( "Enter the name of the kernel file\n"
                 "containing planetary constants       &gt; ",
                 FILSIZ,
                 file                                      );
 
      <a href="../cspice/furnsh_c.html">furnsh_c</a> ( file );
 
 
      <a href="../cspice/prompt_c.html">prompt_c</a> ( "\nEnter the name of the kernel file\n"
                 "containing SCLK coefficients         &gt; ",
                 FILSIZ,
                 file                                      );
 
      <a href="../cspice/furnsh_c.html">furnsh_c</a> ( file );
 
 
      <a href="../cspice/prompt_c.html">prompt_c</a> ( "\nEnter the name of the SPK file\n"
                 "containing planetary and spacecraft\n"
                 "ephemerides                          &gt; ",
                 FILSIZ,
                 file                                      );
 
      <a href="../cspice/furnsh_c.html">furnsh_c</a> ( file );
 
 
      <a href="../cspice/prompt_c.html">prompt_c</a> ( "\nEnter the name of the CK file\n"
                 "containing instrument pointing       &gt; ",
                 FILSIZ,
                 file                                      );
 
      <a href="../cspice/furnsh_c.html">furnsh_c</a> ( file );
 
 
      /*
      Get the names of the spacecraft and target body; get the ID
      code of the instrument.  Convert the instrument ID from
      character to integer.  Translate the spacecraft and target
      names to the corresponding integer codes.
      */
      <a href="../cspice/prompt_c.html">prompt_c</a> ( "\nEnter spacecraft name             &gt; ",
                 BDNMLN,
                 scname                                    );
 
      <a href="../cspice/prompt_c.html">prompt_c</a> ( "\nEnter target name                 &gt; ",
                 BDNMLN,
                 targname                                  );
 
      <a href="../cspice/prompt_c.html">prompt_c</a> ( "Enter NAIF integer instrument ID    &gt; ",
                 INNMLN,
                 instch                                    );
 
      <a href="../cspice/prsint_c.html">prsint_c</a> ( instch, &amp;inst );
      <a href="../cspice/bodn2c_c.html">bodn2c_c</a> ( scname, &amp;sc, &amp;found );
 
      if ( !found )
      {
         <a href="../cspice/setmsg_c.html">setmsg_c</a> ( "Spacecraft name # was not recognized." );
         <a href="../cspice/errch_c.html">errch_c</a>  ( "#", scname                             );
         <a href="../cspice/sigerr_c.html">sigerr_c</a> ( "SPICE(NAMENOTRECOGNIZED)"              );
      }
 
      <a href="../cspice/bodn2c_c.html">bodn2c_c</a> ( targname, &amp;targ, &amp;found );
 
      if ( !found )
      {
         <a href="../cspice/setmsg_c.html">setmsg_c</a> ( "Target body name # was not recognized." );
         <a href="../cspice/errch_c.html">errch_c</a>  ( "#", targname                            );
         <a href="../cspice/sigerr_c.html">sigerr_c</a> ( "SPICE(NAMENOTRECOGNIZED)"               );
      }
 
      /*
      Determine the input epoch.
      */
      <a href="../cspice/prompt_c.html">prompt_c</a> ( "\nEnter SCLK string (blank line to quit) &gt; ",
                 TIMLEN,
                 sclkch                                        );
 
      while (  !<a href="../cspice/iswhsp_c.html">iswhsp_c</a> ( sclkch )  )
      {
         /*
         Convert the input clock string to ticks.
         */
         <a href="../cspice/scencd_c.html">scencd_c</a> ( sc, sclkch, &amp;sclkdp );
 
         /*
         Determine the time tolerance.
         */
         <a href="../cspice/prompt_c.html">prompt_c</a> ( "Enter the tolerance as an SCLK string  &gt; ",
                    TIMLEN,
                    tolch                                       );
 
         /*
         Convert the tolerance to ticks.
         */
         <a href="../cspice/sctiks_c.html">sctiks_c</a> ( sc, tolch, &amp;tol );
 
         /*
         Search the CK file for pointing data at the time sclkdp.
         */
         <a href="../cspice/ckgp_c.html">ckgp_c</a> ( inst, sclkdp, tol, REF, cmat, &amp;clkout, &amp;found );
 
         if ( !found )
         {
            printf ( "\n"
                     "The C-kernel file does not contain "
                     "data for time %s SCLK %s.\n",
                     scname,
                     sclkch                              );
         }
 
         /*
         Compute the inertial pointing vector for the instrument
         boresight.
 
         The boresight vector is assumed to define the z-axis of the
         instrument-fixed frame.  This axis vector can be picked off
         from the third row of the C-matrix.
         */
         <a href="../cspice/vequ_c.html">vequ_c</a> ( cmat[2], vpnt );
 
         /*
         For all other computations, use the ET time corresponding
         to the input SCLK.
         */
         <a href="../cspice/sct2e_c.html">sct2e_c</a> ( sc, sclkdp, &amp;et );
 
         /*
         Compute the target state vector (position and velocity).
         */
         <a href="../cspice/spkez_c.html">spkez_c</a> ( targ, et, REF, "lt+s", sc, vtarg, &amp;tau );
 
         /*
         Get the tibf matrix and radii of target ellipsoid model.
 
         We need tibf for the target as it appeared when the
         instrument took its measurement at time et. The target
         was at its apparent location tau seconds earlier.
 
         <a href="../cspice/tipbod_c.html">tipbod_c</a> and <a href="../cspice/bodvcd_c.html">bodvcd_c</a> will read constants from the planetary
         constants kernel file.
         */
         <a href="../cspice/tipbod_c.html">tipbod_c</a> ( REF,  targ,    et-tau, tibf );
         <a href="../cspice/bodvcd_c.html">bodvcd_c</a> ( targ, "RADII", 3,  &amp;n, r    );
 
         /*
         The position of the observer is just the negative of the
         position part of the spacecraft-target vector, vtarg.
         Note that this is NOT the same as the apparent position of
         the spacecraft as seen from the target.
         */
         <a href="../cspice/vminus_c.html">vminus_c</a> ( vtarg, vpos );
 
         /*
         Put both vectors in body-fixed coordinates.
         */
         <a href="../cspice/mxv_c.html">mxv_c</a> ( tibf, vpos, vpos );
         <a href="../cspice/mxv_c.html">mxv_c</a> ( tibf, vpnt, vpnt );
 
 
         /*
         Compute the point of intersection, if any.
         */
         <a href="../cspice/surfpt_c.html">surfpt_c</a> ( vpos, vpnt, r[0], r[1], r[2], vsurf, &amp;found );
 
 
         if ( !found )
         {
            printf ( "\nThe line-of-sight pointing vector "
                     "does not intersect the target "
                     "at the epoch %s SCLK %s.\n",
                     scname,
                     sclkch                                );
         }
 
         else
         {
            /*
            Convert intersection point from rectangular to lat-lon-
            radius coordinates.
            */
            <a href="../cspice/reclat_c.html">reclat_c</a> ( vsurf, &amp;radius, &amp;lon, &amp;lat );
 
 
            printf ( "\n"
                     "Radius (km)         %f\n"
                     "Longitude (deg)     %f\n"
                     "Latitude (deg)      %f\n"
                     "\n",
                     radius,
                     lon * <a href="../cspice/dpr_c.html">dpr_c</a>(),
                     lat * <a href="../cspice/dpr_c.html">dpr_c</a>()             );
 
         }
 
         /*
         Input next epoch.
         */
         <a href="../cspice/prompt_c.html">prompt_c</a> ( "\nEnter SCLK string (blank line to quit) &gt; ",
                    TIMLEN,
                    sclkch                                        );
      }
 
      return (0);
   }
</PRE>
<BR><BR>
<A NAME="Appendix C --- An Example of Writing a Type 1 CK Segment"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Appendix C --- An Example of Writing a Type 1 CK Segment
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   The following example shows how one might write a program to create or
   add to a C-kernel file.
<P>
 
   The program creates a single type 1 segment for the scan platform of the
   Galileo spacecraft. Assume that C-matrices, angular velocity vectors,
   and the associated SCLK time strings are contained in time-ordered
   arrays assumed to have been initialized elsewhere (by the function
   `get_gll_pnt' --- not part of CSPICE). The program provides the option
   of adding the segment to an existing file, or creating a new file.
<P>
 
<PRE>
      /*
      Local variables
      */
      SpiceChar                ck      [FILSIZ];
      SpiceChar                sclkch  [MAXREC][CLKLEN];
 
      SpiceDouble              avvs    [MAXREC][3];
      SpiceDouble              begtim;
      SpiceDouble              cmats   [MAXREC][3][3];
      SpiceDouble              endtim;
      SpiceDouble              quats   [MAXREC][4];
      SpiceDouble              sclkdp  [MAXREC];
 
      SpiceInt                 handle;
      SpiceInt                 i;
      SpiceInt                 nprec;
 
 
      /*
      Can either add to an existing CK file or create a brand
      new one.
      */
      printf ( "You may either add to an existing CK file, or "
               "create a new one.\n"                            );
 
      <a href="../cspice/prompt_c.html">prompt_c</a> ( "Enter the name of the CK file to create &gt; ",
                 FILSIZ,
                 ck                                           );
 
 
      /*
      To convert SCLK times from clock strings to encoded SCLK,
      we need to load the Galileo spacecraft clock kernel file into
      the kernel pool.  Assume that the file is called gll_sclk.tsc.
      */
      <a href="../cspice/furnsh_c.html">furnsh_c</a> ( SCLKKER );
 
 
      /*
      To open a new CK file use <a href="../cspice/ckopn_c.html">ckopn_c</a>, and for an existing
      file use <a href="../cspice/dafopw_c.html">dafopw_c</a>.
      */
      if (  <a href="../cspice/exists_c.html">exists_c</a> ( ck )  )
      {
         dafopw_ ( ck, &amp;handle, strlen(ck) );
      }
      else
      {
         <a href="../cspice/ckopn_c.html">ckopn_c</a> ( ck, ck, 0, &amp;handle );
      }
 
 
      /*
      Get the pointing information to go in the C-kernel segment.
 
         1) Number of pointing instances returned
         2) Array of SCLK times
         3) Array of C-matrices, dimension [][3][3]
         4) Array of angular velocity vectors, dimension [][3]
 
      */
      get_gll_pnt ( &amp;nprec, CLKLEN, sclkch, cmats, avvs );
 
 
      /*
      Now convert the times to encoded SCLK.
      */
      for ( i = 0;  i &lt; nprec;  i++ )
      {
         <a href="../cspice/scencd_c.html">scencd_c</a> ( GLL, sclkch[i], sclkdp+i );
      }
 
      /*
      Set the segment boundaries equal to the first and last
      time in the segment.
      */
      begtim = sclkdp[      0];
      endtim = sclkdp[nprec-1];
 
      /*
      The C-matrices are represented by quaternions in a type 1 CK
      segment.  The CSPICE routine <a href="../cspice/m2q_c.html">m2q_c</a> converts C-matrices to
      quaternions.
      */
 
      for ( i = 0;  i &lt; nprec;  i++ )
      {
         <a href="../cspice/m2q_c.html">m2q_c</a> ( cmats[i], quats[i] );
      }
 
 
      /*
      The constants that will go into the segment descriptor are
 
         AVFLAG ... Angular velocity flag.  Set to SPICETRUE.
         INST   ... NAIF Instrument ID code.  Set to -77001.
         REF    ... Name of inertial reference frame.  Set to "B1950".
         SEGID  ... Segment identifer.  Set to
 
                      "GLL SCAN PLT - NAIF - 18-NOV-90"
 
 
      That is all the information that we need. Write the segment.
      */
 
      <a href="../cspice/ckw01_c.html">ckw01_c</a> ( handle,
                begtim,
                endtim,
                INST,
                REF,
                AVFLAG,
                SEGID,
                nprec,
                sclkdp,
                quats,
                avvs    );
 
      /*
      Close the file.
      */
      <a href="../cspice/ckcls_c.html">ckcls_c</a> ( handle );
 
      return (0);
   }
</PRE>
<BR><BR>
<A NAME="Appendix D --- An Example of Writing a Type 2 CK Segment"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Appendix D --- An Example of Writing a Type 2 CK Segment
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   This example program creates a single type 2 segment of predict pointing
   for the scan platform of the Galileo spacecraft.
<P>
 
   This program will use data type 2 to store pointing information for time
   intervals during which the pointing of the scan platform is constant. It
   is assumed that a function called `gll_const_pnt' will provide ordered
   arrays of C-matrices and interval start and stop times. The Ith C-matrix
   represents the fixed platform pointing during the Ith interval. Assume
   that the start and stop times are given in Galileo clock string form so
   that they must be converted into encoded SCLK for use in the C-kernel.
<P>
 
<PRE>
   /*
 
   PROGRAM WRTCK2
 
      Write a type 2 CK segment to a new or existing C-kernel.
      This example assumes the existence of a user-supplied
      function to return time-tagged pointing values.
 
   */
 
   #include &lt;stdio.h&gt;
   #include &lt;string.h&gt;
   #include "SpiceUsr.h"
   #include "SpiceZfc.h"
 
   int main()
   {
 
      /*
      Functions
      */
      void gll_const_pnt ( SpiceInt       * nprec,
                           SpiceInt         sclklen,
                           void           * begch,
                           void           * endch,
                           SpiceDouble  ( * cmats  )[3][3] );
 
      /*
      Local constants
      */
      #define  CLKLEN         30
      #define  FILSIZ         256
      #define  GLL            -77
      #define  IFNAME         "Test CK created by wrtck.c"
      #define  INST           -77001
      #define  MAXREC         10000
      #define  NCOMCH         1000
      #define  REF            "B1950"
      #define  REFLEN         10
      #define  SCLKKER        "gll_sclk.tsc"
      #define  SECPERTICK     ( 1. / 120. )
      #define  SEGID          "GLL SCAN PLT - NAIF - TYPE 2 PREDICT"
      #define  SIDLEN         40
 
 
      /*
      Local variables
      */
      SpiceChar                ck      [FILSIZ];
      SpiceChar                begch   [MAXREC][CLKLEN];
      SpiceChar                endch   [MAXREC][CLKLEN];
 
      SpiceDouble              avvs    [MAXREC][3];
      SpiceDouble              begtim;
      SpiceDouble              cmats   [MAXREC][3][3];
      SpiceDouble              endtim;
      SpiceDouble              quats   [MAXREC][4];
      SpiceDouble              rates   [MAXREC];
      SpiceDouble              start   [MAXREC];
      SpiceDouble              stop    [MAXREC];
 
      SpiceInt                 handle;
      SpiceInt                 i;
      SpiceInt                 nprec;
 
 
      /*
      Can either add to an existing CK file or create a brand
      new one.
      */
      printf ( "You may either add to an existing CK file, or "
               "create a new one.\n"                            );
 
      <a href="../cspice/prompt_c.html">prompt_c</a> ( "Enter the name of the CK file to create &gt; ",
                 FILSIZ,
                 ck                                           );
 
 
      /*
      To convert SCLK times from clock string to encoded SCLK,
      we need to load the Galileo spacecraft clock kernel file into
      the kernel pool.  Assume that the file is called gll_sclk.tsc.
      */
      <a href="../cspice/furnsh_c.html">furnsh_c</a> ( SCLKKER );
 
 
      /*
      To open a new CK file use <a href="../cspice/ckopn_c.html">ckopn_c</a>, and for an existing
      file use <a href="../cspice/dafopw_c.html">dafopw_c</a>.
      */
      if (  <a href="../cspice/exists_c.html">exists_c</a> ( ck )  )
      {
         dafopw_ ( ck, &amp;handle, strlen(ck) );
      }
      else
      {
         <a href="../cspice/ckopn_c.html">ckopn_c</a> ( ck, ck, 0, &amp;handle );
      }
 
 
      /*
      Get the pointing information to go in the C-kernel segment.
 
         1) Number of pointing instances returned
         2) Interval start times in clock string form
         3) Interval stop times in clock string form
         3) Array of C-matrices, dimension [][3][3]
 
      */
      gll_const_pnt ( &amp;nprec, CLKLEN, begch, endch, cmats );
 
 
      /*
      Now convert the times to encoded SCLK.
      */
      for ( i = 0;  i &lt; nprec;  i++ )
      {
         <a href="../cspice/scencd_c.html">scencd_c</a> ( GLL, begch[i], start+i );
         <a href="../cspice/scencd_c.html">scencd_c</a> ( GLL, endch[i], stop +i );
      }
 
 
      /*
      Set the segment boundaries equal to the first and last
      time in the segment.
      */
      begtim = start[      0];
      endtim = stop [nprec-1];
 
 
      /*
      The C-matrices are represented by quaternions in a type 1 CK
      segment.  The CSPICE routine <a href="../cspice/m2q_c.html">m2q_c</a> converts C-matrices to
      quaternions.
      */
      for ( i = 0;  i &lt; nprec;  i++ )
      {
         <a href="../cspice/m2q_c.html">m2q_c</a> ( cmats[i], quats[i] );
      }
 
 
      /*
      Since the pointing is constant over each interval, each angular
      velocity vector is zero.
      */
      for ( i = 0;  i &lt; (3*nprec);  i++ )
      {
        *( (SpiceDouble *)avvs+i ) = 0.;
      }
 
 
      /*
      Since this is a predict segment the number of seconds
      represented by one tick during each of the intervals will
      be set equal to the nominal amount of time represented by
      the least significant field of the Galileo clock: 1/120 sec.
      */
      for ( i = 0;  i &lt; nprec;  i++ )
      {
         rates[i] = SECPERTICK;
      }
 
 
      /*
      The constants that will go into the segment descriptor are
 
         INST   ... NAIF Instrument ID code.  Set to -77001.
 
         REF    ... Name of inertial reference frame.  Set to
                    "B1950".
 
         SEGID  ... Segment identifer.  Set to
 
                      "GLL SCAN PLT - NAIF - TYPE 2 PREDICT"
 
 
      That is all the information that we need. Write the segment.
      */
      <a href="../cspice/ckw02_c.html">ckw02_c</a> ( handle,
                begtim,
                endtim,
                INST,
                REF,
                SEGID,
                nprec,
                start,
                stop,
                quats,
                avvs,
                rates    );
 
      /*
      Close the file.
      */
      <a href="../cspice/ckcls_c.html">ckcls_c</a> ( handle );
 
      return (0);
   }
</PRE>
<BR><BR>
<A NAME="Appendix E --- An Example of Writing a Type 3 CK Segment"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Appendix E --- An Example of Writing a Type 3 CK Segment
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   The following example program shows how one might write a type 3
   C-kernel segment to a new file.
<P>
 
   The program creates a single type 3 segment for a two hour time period
   for the Mars Global Surveyor spacecraft bus. The program calculates the
   pointing instances directly from the spacecraft and planet ( SPK )
   ephemeris file.
<P>
 
   The names of the input ephemeris, leapseconds, spacecraft clock, and
   planetary constants kernel files are fictitious.
<P>
 
<PRE>
   /*
 
   PROGRAM WRTCK3
 
      This program creates a predict type 3 CK segment for the
      Mars Global Surveyor spacecraft.
 
   */
 
   #include &lt;stdio.h&gt;
   #include "SpiceUsr.h"
 
 
   int main()
   {
 
      /*
      Functions
      */
      void get_dervrt ( SpiceDouble     epoch,
                        SpiceDouble     dcmat[3][3] );
 
      void locvrt_m__ ( SpiceInt        center,
                        SpiceInt        sc,
                        SpiceDouble     epoch,
                        SpiceChar     * ref,
                        SpiceChar     * abcorr,
                        SpiceDouble     cmat  [3][3] );
 
      /*
      Local constants
      */
 
      /*
      Names of kernels:  LSK, SCLK, PCK, SPK, CK.
      */
      #define  LSK            "leap.tls"
      #define  SCLKKER        "mgs.tsc"
      #define  PCK            "mgs.tpc"
      #define  SPK            "mgs.bsp"
      #define  CK             "mgs_predict_ck.bc"
 
      /*
      The internal file name:  just set this equal to the CK name.
      */
      #define  IFNAME         CK
 
      /*
      The segment identifier:
      */
      #define  SEGID          "MGS PREDICT TYPE 3 SEGMENT"
 
      /*
      The number of characters to reserve in the comment area
      when creating the file:
      */
      #define  NCOMCH         0
 
      /*
      The reference frame of the segment is J2000.
      */
      #define  REF            "J2000"
 
      /*
      Assign the NAIF body id codes for the Mars Global Surveyor
      spacecraft and Mars.
      */
      #define  CENTERNAME     "Mars"
      #define  SCNAME         "MGS"
 
 
      /*
      The ID code for the MGS spacecraft bus:
      */
      #define  INST           -94000
 
      /*
      The angular velocity flag will indicate that angular velocity
      data are available.
      */
      #define  AVFLAG         SPICETRUE
 
 
      /*
      We will need about 2000 pointing instances.
      */
      #define  MAXREC         2000
 
      /*
      The segment begin and end times.
      */
      #define  UTCBEG         "1994 JAN 21 00:00:00"
      #define  UTCEND         "1994 JAN 21 02:00:00"
 
      /*
      The time step separating the time tags of the pointing
      instances.  The units are ticks of encoded SCLK.
      */
      #define  SCLKSTEP       1024.0
 
 
      /*
      Local variables
      */
      SpiceBoolean            found;
 
      SpiceDouble             avvs    [MAXREC][3];
      SpiceDouble             begtime;
      SpiceDouble             cmat    [3][3];
      SpiceDouble             dcmat   [3][3];
      SpiceDouble             endtime;
      SpiceDouble             epoch;
      SpiceDouble             etBeg;
      SpiceDouble             etEnd;
      SpiceDouble             omega   [3][3];
      SpiceDouble             quats   [MAXREC][4] ;
      SpiceDouble             scBeg;
      SpiceDouble             scEnd;
      SpiceDouble             sclk;
      SpiceDouble             sclkdp  [MAXREC];
      SpiceDouble             start   [MAXREC];
 
      SpiceInt                ckhan;
      SpiceInt                i;
      SpiceInt                nint;
      SpiceInt                nrec;
      SpiceInt                SCID;
 
      SpiceInt                centerID;
 
 
      /*
      Translate the spacecraft and central body names to
      NAIF ID codes.
      */
      <a href="../cspice/bodn2c_c.html">bodn2c_c</a> ( SCNAME,     &amp;SCID,  &amp;found );
 
</PRE>
<PRE>
      if ( !found )
      {
         <a href="../cspice/setmsg_c.html">setmsg_c</a> ( "Name # could not be mapped to a NAIF ID code." );
         <a href="../cspice/errch_c.html">errch_c</a>  ( "#",  SCNAME                                    );
         <a href="../cspice/sigerr_c.html">sigerr_c</a> ( "SPICE(NAMENOTFOUND)"                           );
      }
 
      <a href="../cspice/bodn2c_c.html">bodn2c_c</a> ( CENTERNAME, &amp;centerID, &amp;found );
 
      if ( !found )
      {
         <a href="../cspice/setmsg_c.html">setmsg_c</a> ( "Name # could not be mapped to a NAIF ID code." );
         <a href="../cspice/errch_c.html">errch_c</a>  ( "#",  CENTERNAME                                );
         <a href="../cspice/sigerr_c.html">sigerr_c</a> ( "SPICE(NAMENOTFOUND)"                           );
      }
</PRE>
<PRE>
 
      /*
      Load the binary SPK file that provides states for MGS with
      respect to Mars for the time period of interest.
      */
      <a href="../cspice/furnsh_c.html">furnsh_c</a> ( SPK );
 
      /*
      Load the text leapseconds, spacecraft clock ( sclk ), and
      planetary constants ( pck ) files into the kernel pool.
      */
      <a href="../cspice/furnsh_c.html">furnsh_c</a> ( LSK     );
      <a href="../cspice/furnsh_c.html">furnsh_c</a> ( SCLKKER );
      <a href="../cspice/furnsh_c.html">furnsh_c</a> ( PCK     );
 
      /*
      Convert the segment begin and end times first to ET then to
      MGS spacecraft clock.
      */
      <a href="../cspice/str2et_c.html">str2et_c</a> ( UTCBEG, &amp;etBeg );
      <a href="../cspice/str2et_c.html">str2et_c</a> ( UTCEND, &amp;etEnd );
 
      <a href="../cspice/sce2c_c.html">sce2c_c</a>  ( SCID, etBeg, &amp;scBeg );
      <a href="../cspice/sce2c_c.html">sce2c_c</a>  ( SCID, etEnd, &amp;scEnd );
 
 
      /*
      Calculate the quaternions and angular velocity vectors at
      roughly four second intervals from the segment start time
      until the end.
      */
 
      for (  ( i = 0,            sclk =  scBeg    );
             ( i &lt; MAXREC ) &amp;&amp; ( sclk &lt;= scEnd    );
             ( i++,              sclk += SCLKSTEP )   )
      {
 
         /*
         The times stored in the C-kernel are always in encoded
         spacecraft clock form.  SPK takes ET as the input time.
         */
         sclkdp[i] = sclk;
 
         <a href="../cspice/sct2e_c.html">sct2e_c</a> ( SCID, sclk, &amp;epoch );
 
         /*
         Find the C-matrix using the non-CSPICE routine locvrt_m__.
         locvrt_m__ returns the 3x3 matrix that transforms vectors
         from a specified inertial reference frame to the `Local
         Vertical Frame' for a specified observer and target body.
         This frame is defined as follows:
 
 
            Z-axis:  The unit vector pointing from the orbiter to
                     the sub-orbiter point on the extended body.  This
                     point is the closest point on the body to the
                     orbiter; thus the unit outward normal vector on
                     the body's surface is the negative of the
                     Z-vector.
 
 
            Y-axis:  The unitized cross product
 
                        Z x V
 
                     where V is the orbiter's inertially referenced
                     velocity vector.
 
 
            X-axis:  The cross product
 
                        Y x Z
 
                     (Z and Y are already orthonormal, so X is a unit
                     vector.)
 
 
         In the call below, the argument "NONE" indicates that the
         vectors defining the frame are not to be corrected for
         light time or stellar aberration.
         */
 
         locvrt_m__ ( centerID, SCID,  epoch,       REF,
                      "NONE",   cmat,  strlen(REF), 4   );
 
         <a href="../cspice/m2q_c.html">m2q_c</a> ( cmat, quats[i] );
 
 
         /*
         Calculate the angular velocity vector using the following
         formula:
 
         Let the angular velocity vector be  AV = ( a1, a2, a3 )
         and let the matrix OMEGA be:
 
                     +--              --+
                     |   0   -a3   a2   |
                     |                  |
            OMEGA =  |  a3    0    -a1  |
                     |                  |
                     |  -a2   a1    0   |
                     +--              --+
 
          Then the derivative of a C-matrix C is given by
 
                                   t
                      t       d [ C ]
             OMEGA * C   =    -------
                                 dt
 
          Thus, given a C-matrix and its derivative, the angular
          velocity can be calculated from
 
                              t
                          d[ C  ]
              OMEGA  =    -------  *  C
                             dt
 
 
 
         get_dervrt is a non-CSPICE routine that will calculate
         the derivative of the C-matrix calculated by locvrt_m__.
         */
         get_dervrt ( epoch, dcmat );
 
         <a href="../cspice/mtxm_c.html">mtxm_c</a> ( dcmat, cmat, omega );
 
         avvs[i][0]  =  omega[2][1];
         avvs[i][1]  =  omega[0][2];
         avvs[i][2]  =  omega[1][0];
      }
 
      /*
      Set the pointing record count and the segment time bounds.
      */
      nrec    -= i;
 
      begtime =  sclkdp[0];
      endtime =  sclkdp[nrec-1];
 
 
      /*
      Unload the SPK file.
      */
      <a href="../cspice/unload_c.html">unload_c</a> ( SPK );
 
 
      /*
      The process of determining how to partition the pointing
      instances into interpolation intervals varies with respect
      to the means by which the pointing instances are obtained.
 
      For this example program it is acceptable to interpolate
      between all of the adjacent pointing instances because:
 
      1) The pointing was calculated at every 4 seconds so there
         are no gaps in the data.
 
      2) The pointing was calculated directly from the spacecraft
         and planetary ephemeris so that the functions for the
         spacecraft axis and angular velocity vectors will change
         "slowly" and continuously.
 
      Therefore there is only one interpolation interval for the
      entire segment.
      */
 
      nint     =  1;
      start[0] =  sclkdp[0];
 
 
      /*
      Now that the pointing instances have been calculated the
      segment can be written to a C-kernel file.
 
      Open a new file.
      */
      <a href="../cspice/ckopn_c.html">ckopn_c</a> ( CK, IFNAME, NCOMCH, &amp;ckhan );
 
 
      /*
      The values that will go in the segment descriptor are
      already set.  These are:
 
         1) The NAIF ID code for the MGS spacecraft bus INST.
         2) The angular velocity flag AVFLAG.
         3) The segment start and stop times scBeg and scEnd.
         4) The reference frame REF.
         5) The segment time bounds begtime and endtime.
 
      The segment identifier SEGID is set as well.
 
         1) Number of pointing instances returned
         2) Interval start times in clock string form
         3) Interval stop times in clock string form
         3) Array of C-matrices, dimension [][3][3]
 
      */
 
 
      /*
      Write the segment to the file attached to HANDLE.
      */
      <a href="../cspice/ckw03_c.html">ckw03_c</a> ( ckhan,  begtime, endtime, INST,   REF,    AVFLAG,
                SEGID,  nrec,    sclkdp,  quats,  avvs,   nint,
                start                                           );
 
      /*
      Close the file.
      */
      <a href="../cspice/ckcls_c.html">ckcls_c</a> ( ckhan );
 
      return (0);
 
   }
</PRE>
<BR><BR>
<A NAME="Appendix G: Document Revision History"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> Appendix G: Document Revision History
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
<BR><BR>
<A NAME="April 1, 2009"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> April 1, 2009
</H3><P><BR><BR>
   Added a note about the SPICE file identification word for CK kernels.
<P>
 
<BR><BR>
<A NAME="November 17, 2005"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> November 17, 2005
</H3><P><BR><BR>
   Abstract was added.
<P>
 
   Calls/references to the deprecated routine <a href="../cspice/bodvar_c.html">bodvar_c</a> were replaced with
   calls/referenes to <a href="../cspice/bodvcd_c.html">bodvcd_c</a>. <a href="../cspice/bodvrd_c.html">bodvrd_c</a> is mentioned as another routine
   superseding <a href="../cspice/bodvar_c.html">bodvar_c</a>.
<P>
 
   C examples showing incorrect calling sequences for <a href="../cspice/prompt_c.html">prompt_c</a> were
   corrected.
<P>
 
<BR><BR>
<A NAME="December 21, 2004"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> December 21, 2004
</H3><P><BR><BR>
   Replaced references and examples of lower level CK loading/unloading
   functions with <a href="../cspice/furnsh_c.html">furnsh_c</a>/<a href="../cspice/unload_c.html">unload_c</a>.
<P>
 
<BR><BR>
<A NAME="February 2, 2004"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> February 2, 2004
</H3><P><BR><BR>
   Performed a spell-check on text.
<P>
 
<BR><BR>
<A NAME="September 04, 2002"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> September 04, 2002
</H3><P><BR><BR>
   Added a discussion of CK type 05.
<P>
 
   Added a brief discussion of the DAF run-time binary file format
   translation capability now present in the SPICE Toolkit.
<P>
 
<BR><BR>
<A NAME="February 15, 2000"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> February 15, 2000
</H3><P><BR><BR>
   This February 2000 version of the document differs from the previous
   version of October 1999 in the following areas:
<P>
 
   The section describing new Chebyshev polynomial based data type--CK Type
   4--was added to the document.
<P>
 
<BR><BR>
<A NAME="October 14, 1999"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> October 14, 1999
</H3><P><BR><BR>
   This is the initial release of the CSPICE edition of the CK "Required
   Reading" document.
<P>
 
<BR><BR>
<A NAME="Overview of the October 14, 1999 revision"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Overview of the October 14, 1999 revision
</H3><P><BR><BR>
   The SPICE system has been extended to include CSPICE---a version of the
   NAIF Toolkit software coded in the ANSI C programming language.
<P>
 
   The CSPICE library---the C counterpart of SPICELIB---consists of two
   categories of functions:
<P>
 
<UL>
<TT>--</TT> Low level functions, translated from Fortran to ANSI C via the automatic
translation program f2c.
<BR><BR></UL>
<UL>
<TT>--</TT> Application interface-level functions, hand-coded in ANSI C. These
hand-coded functions are called ``wrappers'' since they typically serve to
encapsulate C code generated by running f2c on Fortran source code.
<BR><BR></UL>
   Wrapper functions are denoted by names ending with the suffix
<P>
 
<PRE>
   _c
</PRE>
   Functions created by f2c have names ending with the suffix
<P>
 
<PRE>
   _
</PRE>
   In this first version of CSPICE, wrappers are provided for the principal
   C application interface functions. Hand-coded versions of other, less
   frequently used interface functions will be supplied in a later version
   of CSPICE. The remaining, lower-level functions will not be provided
   with wrappers.
<P>
 
   The set of currently available CSPICE CK wrapper functions is:
<P>
 
<PRE>
   <a href="../cspice/ckcls_c.html">ckcls_c</a>
   <a href="../cspice/ckgp_c.html">ckgp_c</a>
   <a href="../cspice/ckgpav_c.html">ckgpav_c</a>
   <a href="../cspice/furnsh_c.html">furnsh_c</a>
   <a href="../cspice/ckopn_c.html">ckopn_c</a>
   <a href="../cspice/unload_c.html">unload_c</a>
   <a href="../cspice/ckw01_c.html">ckw01_c</a>
   <a href="../cspice/ckw02_c.html">ckw02_c</a>
   <a href="../cspice/ckw03_c.html">ckw03_c</a>
</PRE>
   Less frequently used application interface-level functions referenced
   here but for which wrappers are not yet implemented are:
<P>
 
<PRE>
   Portions of the DAF family of functions
   The SPC family of functions
</PRE>

</TD>
</TR>
</TBODY>
</TABLE>

</BODY>

</HTML>
